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Foreword 



This Technical Specification has been produced by the 3 r Generation Partnership Project (3GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 
where: 

x the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 5 of a multi-part TS covering the 3 r Generation Partnership Project: Technical 
Specification Group Core Network; Open Service Access (OSA); Application Programming Interface (API), as 
identified below. The API specification (3GPP TS 29.198) is structured in the following Parts: 



Parti 
Part 2 
Part 3 
Part 4 



Part 5 

Part 6 

Part 7 
Part 8 
Part 9 
Part 10 
Part 11 
Part 12 
Part 13 
Part 14 
Part 15 
Part 16 



"Overview"; 

"Common Data Definitions"; 

"Framework"; 

"Call Control"; 

Sub-part 1: "Call Control Common Definitions"; 

Sub-part 2: "Generic Call Control SCF"; 

Sub-part 3: "Multi-Party Call Control SCF"; 

Sub-part 4: "Multi-Media Call Control SCF"; 

Sub-part 5: "Conference Call Control SCF"; 

"User Interaction SCF"; 

"Mobility SCF"; 

"Terminal Capabilities SCF"; 

"Data Session Control SCF"; 

"Generic Messaging SCF"; 

"Connectivity Manager SCF"; 

"Account Management SCF"; 

"Charging SCF". 

"Policy Management SCF"; 

"Presence and Availability Management SCF"; 

"Multi Media Messaging SCF"; 

"Service Broker SCF". 



(not part of 3GPP Release 8) 
(new in 3GPP Release 8) 



The Mapping specification of the OSA APIs and network protocols (3GPP TR 29.998) is also structured as above. 
A mapping to network protocols is however not applicable for all Parts, but the numbering of Parts is kept. 
Also in case a Part is not supported in a Release, the numbering of the parts is maintained. 
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Table: Overview of the OSA APIs & Protocol Mappings 29.198 & 29.998-family 



OSA API specifications 29.198-family 


OSA API Mapping - 29.998-family 


29.198-01 


Overview 


29.998-01 


Overview 


29.198-02 


Common Data Definitions 


29.998-02 


Not Applicable 


29.198-03 


Framework 


29.998-03 


Not Applicable 


Call 
Control 

(CC) 
SCF 


29.198- 
04-1 

Common 
CC data 
definitions 


29.198- 
04-2 
Generic 
CCSCF 


29.198- 
04-3 
Multi- 
Party CC 
SCF 


29.198- 
04-4 
Multi- 
media CC 
SCF 


29.998-04-1 


Generic Call Control - CAP mapping 


29.998-04-2 


Generic Call Control - INAP mapping 


29.998-04-3 


Generic Call Control - Megaco mapping 


29.998-04-4 


Multiparty Call Control - ISC mapping 


29.198-05 


User Interaction SCF 


29.998-05-1 


User Interaction - CAP mapping 


29.998-05-2 


User Interaction - INAP mapping 


29.998-05-3 


User Interaction - Megaco mapping 


29.998-05-4 


User Interaction - SMS mapping 


29.198-06 


Mobility SCF 


29.998-06 


User Status and User Location - MAP mapping 


29.198-07 


Terminal Capabilities SCF 


29.998-07 


Not Applicable 


29.198-08 


Data Session Control SCF 


29.998-08 


Data Session Control - CAP mapping 


29.198-09 


Generic Messaging SCF 


29.998-09 


Not Applicable 


29.198-10 


Connectivity Manager SCF 


29.998-10 


Not Applicable 


29.198-11 


Account Management SCF 


29.998-11 


Not Applicable 


29.198-12 


Charging SCF 


29.998-12 


Not Applicable 


29.198-13 


Policy Management SCF 


29.998-13 


Not Applicable 


29.198-14 


Presence & Availability Management SCF 


29.998-14 


Not Applicable 


29.198-15 


Multi Media Messaging SCF 


29.998-15 


Not Applicable 


29.198-16 


Service Broker SCF 


29.998-16 
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Scope 



This document is Part 5 of the Stage 3 specification for an Application Programming Interface (API) for Open Service 
Access (OSA). 

The OSA specifications define an architecture that enables application developers to make use of network functionality 
through an open standardised interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA 
are contained in 3GPP TS 23.198 [3], The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the User Interaction (UI) Service Capability Feature (SCF) aspects of the interface. All 
aspects of the User Interaction SCF are defined here, these being: 

Sequence Diagrams 

Class Diagrams 

Interface specification plus detailed method descriptions 

State Transition diagrams 

Data definitions 

IDL Description of the interfaces 

WSDL Description of the interfaces 

Reference to the Java™ API description of the interfaces 

The process by which this task is accomplished is through the use of object modelling techniques described by the 
Unified Modelling Language (UML). 

This specification has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group, in co- 
operation with a number of JAIN™ Community member companies. 

Maintenance of up to 3GPP Rel-8 and new OSA Stage 1, 2 and 3 work beyond Rel-9 was moved to OMA in June 2008. 



References 



The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TS 29.198-1: "Open Service Access; Application Programming Interface; Part 1: 

Overview" . 

[2] 3GPP TS 22.127: "Service Requirement for the Open Services Access (OSA); Stage 1". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] Speech Recognition Grammar Specification Version 1 : http://www.w3.org/TR/2004/REC-speech- 

grammar-20040316/ 
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Definitions and abbreviations 



3.1 



Definitions 



For the purposes of the present document, the terms and definitions given in TS 29.198-1 [1] apply. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in TS 29.198-1 [1] apply. 

4 Generic and Call User Interaction and Administration 

SCF 



4.1 



Generic and Call User Interaction SCF 



The Generic User Interaction service capability feature is used by applications to interact with end users. It consists of 
three interfaces: 

1) User Interaction Manager, containing management functions for User Interaction related issues. 

2) Generic User Interaction, containing methods to interact with an end-user. 

3) Call User Interaction, containing methods to interact with an end-user engaged in a call. 

The Generic User Interaction service capability feature is described in terms of the methods in the Generic User 
Interaction interfaces. 

The following table gives an overview of the Generic User Interaction methods and to which interfaces these methods 
belong. 

Table 1 : Overview of Generic User Interaction interfaces and their methods 



User Interaction Manager 


Generic User Interaction 


createUI 


sendlnfoReq 


createUICall 


sendlnfoRes 


createNotification 


sendlnfoErr 


destroyUINotification 


sendlnfoAndCollectReq 


reportEventNotification 


sendlnfoAndCollectRes 


userlnteractionAborted 


sendlnfoAndCollectErr 


userlnteractionNotificationlnterrupted 


release 


userlnteractionNotificationContinued 


userlnteractionFaultDetected 


changeNotification 


reportEventRes 


getNotification 


reportEventErr 


enableNotifications 




disableNotifications 




abortMultipleUserlnteractions 




reportEventReq 





The following table gives an overview of the Call User Interaction methods and to which interfaces these methods 
belong. 
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Table 2: Overview of Call User Interaction interfaces and their methods 



User Interaction Manager 


Call User Interaction 


As defined for the Generic User Interaction SCF 


Inherits from Generic User Interaction and adds: 




recordMessageReq 




recordMessageRes 




recordMessageErr 




deleteMessageReq 




deleteMessageRes 




deleteMessageErr 




abortActionReq 




abortActionRes 




abortActionErr 




getMessageReq 




getMessageRes 




getMessageErr 



The IpUI Interface provides functions to send information to, or gather information from the user, i.e. this interface 
allows applications to send SMS and USSD messages. An application can use this interface independently of other 
SCFs. The IpUICall Interface provides functions to send information to, or gather information from the user (or call 
party) attached to a call. 



4.2 Generic User Interaction Administration SCF 

The Generic User Interaction Administration service capability feature is used by application to interact with the service 
to manage the user announcement and recorded messages. It consists of one interface: 

1) User Interaction Administration Manager, containing message management functions for User Interaction. 
Table 3: Overview of Generic User Interaction Administration interfaces and their methods 



User Interaction Administration Manager 



getMessageReq 



putMessageReq 



deleteMessageReq 



getMessageListReq 



4.3 Generic User Interaction SCF Design Aspects 

The following clauses describe each aspect of the Generic User Interaction and Generic User Interaction Administration 
Service Capability Features (SCF). 

The order is as follows: 

• The Sequence diagrams give the reader a practical idea of how each of the SCFs is implemented. 

• The Class relationships clause shows how each of the interfaces applicable to the SCF, relate to one another 

• The Interface specification clause describes in detail each of the interfaces shown within the Class diagram part. 
This clause also includes Call User interaction. 

• The State Transition Diagrams (STD) show the transition between states in the SCF. The states and transitions 
are well-defined; either methods specified in the Interface specification or events occurring in the underlying 
networks cause state transitions. 

• The Data Definitions clause shows a detailed expansion of each of the data types associated with the methods 
within the classes. Note that some data types are used in other methods and classes and are therefore defined 
within the Common Data types part of this specification. 
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4.4 General requirements on support of methods 

An implementation of this API which supports or implements a method described in the present document, shall 
support or implement the functionality described for that method, for at least one valid set of values for the parameters 
of that method. 

Where a method is not supported by an implementation of a Service interface, the exception 
P_METHOD_NOT_SUPPORTED shall be returned to any call of that method. 

Where a method is not supported by an implementation of an Application interface, a call to that method shall be 
possible, and no exception shall be returned. 



5 Sequence Diagrams 

5.1 Generic and Call User Interaction Sequence Diagrams 
5.1.1 Alarm Call 

The following sequence diagram shows a 'reminder message', in the form of an alarm, being delivered to a customer as 
a result of a trigger from an application. Typically, the application would be set to trigger at a certain time, however, the 
application could also trigger on events. 
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: (Loqical 
View::lpAppLoqic) 


: IpAppCall 



IpAppUICall 



IpCallControlManaqer 



: IpCall 



:lpUIManaqer : IpU IC all 




1: This message is used to create an object implementing the IpAppCall interface. 

2: This message requests the object implementing the IpCallControlManager interface to create an object 
implementing the IpCall interface. 

3: Assuming that the criteria for creating an object implementing the IpCall interface (e.g. load control values not 
exceeded) are met it is created. 

4: This message instructs the object implementing the IpCall interface to route the call to the customer destined to 
receive the 'reminder message'. 

5: This message passes the result of the call being answered to its callback object. 

6: This message is used to forward the previous message to the IpAppLogic. 

7: The application requests a new UlCall object that is associated with the call object. 

8: Assuming all criteria are met, a new UlCall object is created by the service. 

9: This message instructs the object implementing the IpUICall interface to send the alarm to the customer's call. 

10: When the announcement ends this is reported to the call back interface. 

1 1: The event is forwarded to the application logic. 
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12: The application releases the UlCall object, since no further announcements are required. Alternatively, the 
application could have indicated P_FINAL_REQUEST in the sendlnfoReq in which case the UlCall object would have 
been implicitly released after the announcement was played. 

13: The application releases the call and all associated parties. 



5.1.2 Call Barring 1 

The following sequence diagram shows a call barring service, initiated as a result of a prearranged event being received 
by the call control service. Before the call is routed to the destination number, the calling party is asked for a PIN code. 
The code is accepted and the call is routed to the original called party. 



: (Logical 



IpAppCall _j_ 

View::lpAppl_oqic) [IpAppCal I Control Manager) I "^^^ IpAppUICall [IpCal I Control Manager 



: IpCall _j_ : IpUICall 

IpUIManager 



1 : new{) 



^ 



2: enableCallNotification( 



4: 'forward event' 



5: newQ 



-*fl 



callEventNotify( ) 



6: createUICall( ) 



: sendlnfoAndCollectReq( 



7: new() 



^h 



^ 



1 G: forward event' 



jj}: sendlnfoAndCollect, 



Res( 



12: routeReq( 



1 4: 'forward event' 



16: "forward! event" 



r 



1'7: deassignCallf ) 



-*tl 



1: This message is used by the application to create an object implementing the IpAppCallControlManager interface. 

2: This message is sent by the application to enable notifications on new call events. As this sequence diagram depicts 
a call barring service, it is likely that all new call events destined for a particular address or address range prompted for 
a password before the call is allowed to progress. When a new call, that matches the event criteria set, arrives, a 
message (not shown) is directed to the object implementing the IpCallControlManager. Assuming that the criteria for 
creating an object implementing the IpCall interface (e.g. load control values not exceeded) are met, other messages 
(not shown) are used to create the call and associated call leg object. 
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3: This message is used to pass the new call event to the object implementing the IpAppCallControlManager interface. 

4: This message is used to forward the previous message to the IpAppLogic. 

5: This message is used by the application to create an object implementing the IpAppCall interface. The reference to 
this object is passed back to the object implementing the IpCallControlManager using the return parameter of the 
callEventNotify. 

6: This message is used to create a new UlCall object. The reference to the call object is given when creating the 
UlCall. 

7: Provided all the criteria are fulfilled, a new UlCall object is created. 

8: The call barring service dialogue is invoked. 

9: The result of the dialogue, which in this case is the PIN code, is returned to its callback object. 

10: This message is used to forward the previous message to the IpAppLogic. 

1 1: This message releases the UlCall object. 

12: Assuming the correct PIN is entered, the call is forward routed to the destination party. 

13: This message passes the result of the call being answered to its callback object. 

14: This message is used to forward the previous message to the IpAppLogic 

15: When the call is terminated in the network, the application will receive a notification. This notification will always 
be received when the call is terminated by the network in a normal way, the application does not have to request this 
event explicitly. 

16: The event is forwarded to the application. 

17: The application must free the call related resources in the gateway by calling deassignCall. 



5.1 .3 Network Controlled Notifications 

The following sequence diagram shows how an application can receive notifications that have not been created by the 
application, but are provisioned from within the network. 
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AppLoqic 



IpAppUIManaqer 



IpUIManaqer 



1 : new () 



2: ehableNotificationsf ) 



*0 



4: 'forward event' A< 



3: reportNotification( 



a* 



6: 'forward event' ^^ 



5: reportNotification( 



7: di! 



IsableNotificationsf 



^ 



1: The application is started. The application creates a new IpAppUIManager to handle callbacks. 

2: The enableNotifications method is invoked on the IpUIManager interface to indicate that the application is ready to 
receive notifications that are created in the network. For illustrative purposes we assume notifications of type "B" are 
created in the network. 



When a network created trigger occurs the application is notified on the callback interface. 
The event is forwarded to the application. 

When a network created trigger occurs the application is notified on the callback interface. 
The event is forwarded to the application. 



When the application does not want to receive notifications created in the network anymore, it invokes 
disableNotifications on the IpMultiPartyCallConrolManager interface. From now on the gateway will not send any 
notifications to the application that are created in the network. 



5.1.4 Prepaid 



This sequence shows a Pre-paid application. The subscriber is using a pre-paid card or credit card to pay for the call. 
The application each time allows a certain timeslice for the call. After the timeslice, a new timeslice can be started or 
the application can terminate the call. In the following sequence the end-user will received an announcement before his 
final timeslice. 
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Prepaid : (Logical : IpAppCall 

View::lpAppLoqic) 



: IpAppUICall 



: IpCall 



1 :new() 



IpAppCallControlManaqer 

l 

\\ 2:enableCallNotification( 



4: "forward event" 



3:callEventNotify( 



lT 



5: new() 



6:superviseCallReq( 



7: roUteReq( 



*0 



9i: "forward everft^ 

(f 



8:superviseCallRes( 



1 ?: "forward evep£t_ 



10: superviseCallReq( ) 

1 1 :superviseCallRes( 



*0 



13: superviseCallReq( 



-*o 



15: "forward eve 

n< 



tr 



14: s,uperviseCallRes( 



16:oreateUICall( 
17: sendlnfoReq( 



IpCallControlManaqer 


: IpUIManager 





: IpUICall 



^D 



19: "forward ever)t" 



^i<r- 



18: sendlnfoRes( 



20: release( 



21 : superviseCallReq( 



^n 



23: "forward event, 22: s|uperviseCallRes( ) 

A^ rt^ : — 



D 



24: relea'se( 



*0 



1: This message is used by the application to create an object implementing the IpAppCallControlManager interface. 

2: This message is sent by the application to enable notifications on new call events. As this sequence diagram depicts 
a pre-paid service, it is likely that only new call events within a certain address range will be enabled. When a new call, 
that matches the event criteria, arrives a message (not shown) is directed to the object implementing the 
IpCallControlManager. Assuming that the criteria for creating an object implementing the IpCall interface (e.g. load 
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control values not exceeded) are met, other messages (not shown) are used to create the call and associated call leg 
object. 

3: The incoming call triggers the Pre-Paid Application (PPA). 

4: The message is forwarded to the application. 

5: A new object on the application side for the Generic Call object is created. 

6: The Pre-Paid Application (PPA) requests to supervise the call. The application will be informed after the period 
indicated in the message. This period is related to the credits left on the account of the pre-paid subscriber. 

7: Before continuation of the call, PPA sends all charging information, a possible tariff switch time and the call 
duration supervision period, towards the GW which forwards it to the network. 

8: At the end of each supervision period the application is informed and a new period is started. 

9: The message is forwarded to the application. 

10: The Pre-Paid Application (PPA) requests to supervise the call for another call duration. 

1 1 : At the end of each supervision period the application is informed and a new period is started. 

12: The message is forwarded to the application. 

13: The Pre-Paid Application (PPA) requests to supervise the call for another call duration. When the timer expires it 
will indicate that the user is almost out of credit. 

14: When the user is almost out of credit the application is informed. 

15: The message is forwarded to the application. 

16: The application decides to play an announcement to the parties in this call. A new UlCall object is created and 
associated with the call. 

17: An announcement is played informing the user about the near-expiration of his credit limit. 

18: When the announcement is completed the application is informed. 

19: The message is forwarded to the application. 

20: The application releases the UlCall object. 

21: The user does not terminate so the application terminates the call after the next supervision period. 

22: The supervision period ends. 

23: The event is forwarded to the logic. 

24: The application terminates the call. Since the user interaction is already explicitly terminated no 
userlnteractionFaultDetected is sent to the application. 



5.1 .5 Pre-Paid with Advice of Charge (AoC) 

This sequence shows a Pre-paid application that uses the Advice of Charge feature. The application will send the 
charging information before the actual call setup and when during the call the charging changes new information is sent 
in order to update the end-user. Note that the Advice of Charge feature requires an application in the end-user terminal 
to display the charges for the call, depending on the information received from the application. 
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Prepaid : (Logical 
Vi ew::lpAppLoqic) 



Ip AppCal I Control Manager 



: IpAppCall 



: IpAppUICall 



IpCallConti 



1 : new() 



^D 



2: enableCallNotification( 



olManaoer 



: IpCall 



^r 



4: "forward event" 

^< 



3:'callEventNotify( 



,<- 



n<- 



n<- 



1<- 



0^ 



5: new() 



-*d 



10: "forward event" 



13: "forward event 



17: "forward event 



18:new() 



23: "forward event" 



26: "forward event: 



6: setAdyceOfCharg,e( ) 



-> 



7: SiuperviseCallReq( 



8: routeReq( 



n 



^n 



9: supervise CallRes ( ) 



[l 1 : superviseCallR|eq( 



^ 



12: superviseCaHRes( 



14:setAdviceOfChairge( ) 



^> 



15: superviseCallReq( 



^ 



1<- 



16: superviseCallRes( 



^r 



19:createUICall( 



21 : sendlnfoReqf 



22:sendlnfoRe$ ( ) 



-<r 



24:superviseCallReq( 



"0 



25: superviseCallRes( 



27: release( 



: IpUlM anaqer 



^»r 



: IpUICall 



20:new() 



■*Q 



'28: userlnteractionF^iultDetected( 



□*" 



*U 
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1: This message is used by the application to create an object implementing the IpAppCallControlManager interface. 

2: This message is sent by the application to enable notifications on new call events. As this sequence diagram depicts 
a pre-paid service, it is likely that only new call events within a certain address range will be enabled. When a new call, 
that matches the event criteria, arrives a message (not shown) is directed to the object implementing the 
IpCallControlManager. Assuming that the criteria for creating an object implementing the IpCall interface (e.g. load 
control values not exceeded) are met, other messages (not shown) are used to create the call and associated call leg 
object. 

3: The incoming call triggers the Pre-Paid Application (PPA). 

4: The message is forwarded to the application. 

5: A new object on the application side for the Call object is created 

6: The Pre-Paid Application (PPA) sends the AoC information (e.g. the tariff switch time), (it shall be noted the PPA 
contains ALL the tariff information and knows how to charge the user). 

During this call sequence 2 tariff changes take place. The call starts with tariff 1, and at the tariff switch time (e.g. 18:00 
hours) switches to tariff 2. The application is not informed about this (but the end-user is!) 

7: The Pre-Paid Application (PPA) requests to supervise the call. The application will be informed after the period 
indicated in the message. This period is related to the credits left on the account of the pre-paid subscriber. 

8: The application requests to route the call to the destination address. 

9: At the end of each supervision period the application is informed and a new period is started. 

10: The message is forwarded to the application. 

1 1 : The Pre-Paid Application (PPA) requests to supervise the call for another call duration. 

12: At the end of each supervision period the application is informed and a new period is started. 

13: The message is forwarded to the application. 

14: Before the next tariff switch (e.g. 19:00 hours) the application sends a new AOC with the tariff switch time. Again, 
at the tariff switch time, the network will send AoC information to the end-user. 

15: The Pre-Paid Application (PPA) requests to supervise the call for another call duration. When the timer expires it 
will indicate that the user is almost out of credit. 

16: When the user is almost out of credit the application is informed. 

17: The message is forwarded to the application. 

18: The application creates a new call back interface for the User interaction messages. 

19: A new UI Call object that will handle playing of the announcement needs to be created 

20: The Gateway creates a new UI call object that will handle playing of the announcement. 

21: With this message the announcement is played to the parties in the call. 

22: The user indicates that the call should continue. 

23: The message is forwarded to the application. 

24: The user does not terminate so the application terminates the call after the next supervision period. 

25: The user is out of credit and the application is informed. 

26: The message is forwarded to the application. 

27: With this message the application requests to release the call. 
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28: Terminating the call which has still a UlCall object associated will result in a userlnteractionFaultDetected. The 
UlCall object is terminated in the gateway and no further communication is possible between the UlCall and the 
application. 



5.2 Generic User Interaction Administration Sequence 
Diagrams 

5.2.1 Message Administration 

The following sequence diagram shows how an application can manage the user announcement and recorded messages. 



AppLoqic 



IpAppUIAdminManager 



IpUIAdminManager 



1 : new() 



2: putMessageReq( 



^ 



4: 'forward event' 



-<r 



<r 



3: putMessageRes( 



5: getMe|ssageReq( 



^ 



7: 'forward event' 



r^e 



6: getMessageRes( 



!<- 



1: The application is started. The application creates a new IpAppUIAdminManager to handle callbacks. 

2: The putMessageReq method is invoked on the IpUIAdminManager interface to create a new pre-defined message 
for use by sending to the user. 

3: The putMessageRes response notifies the application of the messagelD on the callback interface. 

4: The response is forwarded to the application logic. 
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5: The getMessageReq method is invoked on the IpUIAdminManager interface to retrieve the contents of a user 
announcement or recorded message. 

6: The getMessageRes response notifies the application of the contents of a message. 

7: The event is forwarded to the application. 



6 Class Diagrams 

6.1 Generic and Call User Interaction Class Diagrams 

The application generic user interaction service package consists of one IpAppUIManager interface, zero or more 
IpAppUI interfaces and zero or more IpAppUICall interfaces. 

The generic user interaction service package consists of one IpUIManager interface, zero or more IpUI interfaces and 
zero or more IpUICall interfaces. 

The class diagram in the following figure shows the interfaces that make up the application generic user interaction 
service package and the generic user interaction service package. Communication between these packages is done via 
the «uses» relationships. 

The IpUICall implements call related user interaction and it inherits from the non call related IpUI interface. The same 
holds for the corresponding application interfaces. 



ETSI 



3GPP TS 29.198-05 version 8.0.0 Release 8 



23 



ETSI TS 129 198-5 V8.0.0 (2009-01) 



<<lnterface>> 
^Interface 



«lnterface>> 
IpAppUIManager 



userlnteractionAborted() 

userlnteractionNotificationlnterrupted() 

userlnteractionNotifioationContinued() 

reportEventNotification() 

abortMultipleUserlnteractions() 

<<new>> reportEventReqO 



<<uses» 



<<lnterface>> 
IpUIManager 



createUI() 

createUICall() 

createNotifioation() 

destroyNotification() 

changeNotification() 

getNotificationQ 



<<lnterface>> 
IpAppUl 



sendlnfoResO 

sendlnfoErr() 

sendlnfoAndCollectResO 

sendlnfoAndCollectErr() 

userlnteractionFaultDetectedQ 



<<uses>> 



<<lnterface>> 
IpUl 



sendlnfoReq() 

sendlnfoAndCollectReqO 

release() 

setOriginatingAddress() 

getOriginatingAddress() 

<<new>> reportEventRes() 

<<new>> reportEventErr() 



<<lnterface>> 
IpAppUICall 



recordMessageRes() 

recordMessageErr() 

deleteMessageRes() 

deleteMessageErr() 

abortAotionResO 

abort ActionErr() 

getMessageResO 

getMessageErr() 



■q<uses>> 



<<lnterface>> 
IpUICall 



recordMessageReqO 
deleteM essageReq () 
abortActionReqO 
getMessageReqO 



<< Interfaces 
IpService 



setCallback() 
setCallbackWithSessionlDQ 



Figure: Generic User Interaction Package Overview 



6.2 Generic User Interaction Administration Class Diagrams 

The application generic user administration service package consists of one IpAppUIAdminManager interface and one 
IpUIAdminManager interfaces. 

The class diagram in the following figure shows the interfaces that make up the application generic user administration 
service package. Communication between these packages is done via the «uses» relationships. 
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<<lnterface>> 
Iplnterface 

(from csapi) 



<<lnterface>> 
IpAppUIAdminManager 

*getMessageRes() 

*getMessageErr() 

*deleteMessageRes() 

*deleteMessageErr() 

*putMessageRes() 

^putMessageErrQ 

*getMessageListRes() 

*getMessageListErr() 

A 
«uses>> 



<<lnterface>> 
IpUIAdminManager 



♦getMessageReq() 
♦putMessageReq() 
^deleteMessageReq() 
♦getMessageListReq() 



<<lnterface>> 
IpService 

(from csapi) 

►setCallback() 
►setCallbackWithSession. 



Figure: Generic User Administration Package Overview 



7 The Service Interface Specifications 

7.1 Interface Specification Format 

This clause defines the interfaces, methods and parameters that form a part of the API specification. The Unified 
Modelling Language (UML) is used to specify the interface classes. The general format of an interface specification is 
described below. 



7.1.1 



Interface Class 



This shows a UML interface class description of the methods supported by that interface, and the relevant parameters 
and types. The Service and Framework interfaces for enterprise-based client applications are denoted by classes with 
name Ip<name>. The callback interfaces to the applications are denoted by classes with name IpApp<name>. For 
the interfaces between a Service and the Framework, the Service interfaces are typically denoted by classes with name 
IpSvc<name>, while the Framework interfaces are denoted by classes with name IpFw<name>. 
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7.1.2 Method descriptions 



Each method (API method "call") is described. Both synchronous and asynchronous methods are used in the API. 
Asynchronous methods are identified by a 'Req' suffix for a method request, and, if applicable, are served by 
asynchronous methods identified by either a 'Res' or 'Err' suffix for method results and errors, respectively. To handle 
responses and reports, the application or service developer must implement the relevant IpApp<name> or 
IpSvc<name> interfaces to provide the callback mechanism. 



7.1.3 Parameter descriptions 

Each method parameter and its possible values are described. Parameters described as 'in' represent those that must have 
a value when the method is called. Those described as 'out' are those that contain the return result of the method when 
the method returns. 

7.1.4 State Model 

If relevant, a state model is shown to illustrate the states of the objects that implement the described interface. 

7.2 Base Interface 

7.2.1 Interface Class Iplnterface 

All application, framework and service interfaces inherit from the following interface. This API Base Interface does not 
provide any additional methods. 



«lnterface» 
Iplnterface 



7.3 Service Interfaces 
7.3.1 Overview 

The Service Interfaces provide the interfaces into the capabilities of the underlying network - such as call control, user 
interaction, messaging, mobility and connectivity management. 

The interfaces that are implemented by the services are denoted as 'Service Interface'. The corresponding interfaces that 
must be implemented by the application (e.g. for API callbacks) are denoted as Application Interface'. 

7.4 Generic Service Interface 
7.4.1 Interface Class IpService 

Inherits from: Iplnterface. 

All service interfaces inherit from the following interface. 



«lnterface» 
IpService 
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setCallback (applnterface : in IplnterfaceRef) : void 

setCallbackWithSessionID (applnterface : in IplnterfaceRef, sessionID : in TpSessionID) : void 



7.4.1.1 Method setCallback() 

This method specifies the reference address of the callback interface that a service uses to invoke methods on the 
application. It is not allowed to invoke this method on an interface that uses SessionlDs. Multiple invocations of this 
method on an interface shall result in multiple callback references being specified. The SCS shall use the most recent 
callback interface provided by the application using this method. In the event that a callback reference fails or is no 
longer available, the next most recent callback reference available shall be used. 

Parameters 

applnterface : in IplnterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

Raises 

TpCommonExceptions , PINVALIDINTERFACETYPE 



7.4.1.2 Method setCallbackWithSessionlD() 

This method specifies the reference address of the application's callback interface that a service uses for interactions 
associated with a specific session ID: e.g. a specific call, or call leg. It is not allowed to invoke this method on an 
interface that does not use SessionlDs. Multiple invocations of this method on an interface shall result in multiple 
callback references being specified. The SCS shall use the most recent callback interface provided by the application 
using this method. In the event that a callback reference fails or is no longer available, the next most recent callback 
reference available shall be used. 

Parameters 

applnterface : in IplnterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

sessionID : in TpSessionID 

Specifies the session for which the service can invoke the application's callback interface. 

Raises 

TpCommonExceptions, PINVALIDSESSION ID, P INVALIDINTERFACETYPE 



8 Generic User Interaction Interface Classes 

8.1 Generic and Call User Interaction Interface Classes 

The Generic User Interaction Service interface (GUIS) is used by applications to interact with end users. The GUIS is 
represented by the IpUIManager, IpUI and IpUICall interfaces that interface to services provided by the network. To 
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handle responses and reports, the developer must implement IpAppUIManager and IpAppUI interfaces to provide the 
callback mechanism. 

8.1 .1 Interface Class I pU I Manager 

Inherits from: IpService. 

This interface is the 'service manager' interface for the Generic User Interaction Service and provides the management 
functions to the Generic User Interaction Service. 

This interface shall be implemented by a Generic User Interaction SCF. The createUI() method, or the 
createUICall() method, or both the createNotification() and destroyNotification methods, or both the 
enableNotifications() and disableNotificationsQ methods shall be implemented as a minimum requirement. 



«lnterface» 
IpU I Manager 



createUI (appUl : in IpAppUIRef, userAddress : in TpAddress) : TpUlldentifier 

createUICall (appUl : in IpAppUICallRef, uiTargetObject : in TpUITargetObject) : TpUICallldentifier 

createNotification (appUIManager : in IpAppUIManagerRef, eventCriteria : in TpUIEventCriteria) : 
TpAssignmentID 

destroyNotification (assignmentID : in TpAssignmentID) : void 

changeNotification (assignmentID : in TpAssignmentID, eventCriteria : in TpUIEventCriteria) : void 

getNotification () : TpUIEventCriteriaResultSet 

enableNotifications (appUIManager : in IpAppUIManagerRef) : TpAssignmentID 

disableNotifications () : void 



8.1.1.1 Method createUI () 

This method is used to create a new user interaction object for non-call related purposes 

Results: userlnteraction 

Specifies the interface and sessionID of the user interaction created. 

Parameters 

appUl : in IpAppUIRef 

Specifies the application interface for callbacks from the user interaction created. 

userAddress : in TpAddress 

Indicates the end-user with whom to interact. 
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Returns 
TpUIIdentif ier 

Raises 

TpCommonExceptions , PINVALIDNETWORKSTATE , PINVALIDINTERFACETYPE 



8.1.1.2 Method createUICall() 

This method is used to create a new user interaction object for call related purposes. 

The user interaction can take place to the specified party or to all parties in a call. Note that for certain implementation 
user interaction can only be performed towards the controlling call party, which shall be the only party in the call. 

Returns: userlnteraction. 

Specifies the interface and sessionID of the user interaction created. 

Parameters 

appUI : in IpAppUICallRef 

Specifies the application interface for callbacks from the user interaction created. 

uiTargetObject : in TpUITargetObject 

Specifies the object on which to perform the user interaction. This can either be a Call, Multi-party Call or call leg 
object. 

Returns 
TpUICallldentifier 

Raises 

TpCommonExceptions , PINVALIDNETWORKSTATE , PINVALIDINTERFACETYPE 



8.1 .1 .3 Method createNotification() 

This method is used by the application to install specified notification criteria, for which the reporting is implicitly 
activated. If some application already requested notifications with criteria that overlap the specified criteria, or the 
specified criteria overlap with criteria already present in the network (when provisioned from within the network), the 
request is refused with P_INVALID_CRITERIA. 

The criteria are said to overlap if both originating and terminating ranges overlap and the same number plan is used and 
the same servicecode is used. 

If the same application invokes this method multiple times with exactly the same criteria but with different callback 
references, then these shall be treated as additional callback references. Each such notification request shall share the 
same assignmentlD. The gateway shall use the most recent callback interface provided by the application using this 
method. In the event that a callback reference fails or is no longer available, the next most recent callback reference 
available shall be used. 

Returns: assignmentlD 

Specifies the ID assigned by the generic user interaction manager interface for this newly installed notification criteria. 
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Parameters 

appUIManager : in IpAppUIManagerRef 

If this parameter is set (i.e. not NULL) it specifies a reference to the application interface, which is used for callbacks. If 
set to NULL, the application interface defaults to the interface specified via the setCallback() method. 

eventCriteria : in TpUIEventCriteria 

Specifies the event specific criteria used by the application to define the event required, like user address and service 
code. 

Returns 

TpA s s i gnmen t I D 

Raises 

TpCommonExceptions, PINVALIDCRITERIA, PINVALIDINTERFACETYPE 



8.1 .1 .4 Method destroyNotification() 

This method is used by the application to destroy previously installed notification criteria via the createNotification 
method. 

Parameters 

assignment ID : in TpAssignmentID 

Specifies the assignment ID given by the generic user interaction manager interface when the previous 
createNotification() was called. If the assignment ID does not correspond to one of the valid assignment IDs, the 
framework will return the error code P_INVALID_ASSIGNMENT_ID. 

Raises 

TpCommonExceptions, PINVALIDASSIGNMENTID 



8.1 .1 .5 Method changeNotification() 

This method is used by the application to change the event criteria introduced with createNotification method. Any 
stored notification request associated with the specified assignmentID will be replaced with the specified events 
requested. 

Parameters 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the manager interface for the event notification. 

eventCriteria : in TpUIEventCriteria 

Specifies the new set of event criteria used by the application to define the event required. Only events that meet these 
criteria are reported. 
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Raises 

TpCoirunonExceptions, PINVALIDASSIGNMENTID, PINVALIDCRITERIA 



8.1 .1 .6 Method getNotification() 

This method is used by the application to query the event criteria set with createNotification or changeNotification. 

Returns: eventCriteria 

Specifies the event specific criteria used by the application to define the event required. Only events that meet these 
criteria are reported. 

Parameters 

No Parameters were identified for this method. 

Returns 
TpUIEventCriteriaResultSet 

Raises 

TpCommonExc ep t i on s 



8.1 .1 .7 Method enableNotifications() 

This method is used to indicate that the application is able to receive notifications which are provisioned from within 
the network (i.e. these notifications are NOT set using createNotification() but via, for instance, a network management 
system). If notifications provisioned for this application are created or changed, the application is unaware of this until 
the notification is reported. 

If the same application invokes this method multiple times with different IpAppUIManager references, then these shall 
be treated as additional callback references. Each such notification request shall share the same assignmentlD. The 
gateway shall use the most recent callback interface provided by the application using this method. In the event that a 
callback reference fails or is no longer available, the next most recent callback reference available shall be used. 

When this method is used, it is still possible to use createNotification() for service provider provisioned notifications on 
the same interface as long as the criteria in the network and provided by createNotification() do not overlap. However, it 
is NOT recommended to use both mechanisms on the same service manager. 

The methods changeNotification(), getNotification(), and destroyNotification() do not apply to notifications provisioned 
in the network and enabled using enableNotifications(). These only apply to notifications created using 
createNotification() . 

Returns assignmentlD: Specifies the ID assigned by the manager interface for this operation. This ID is contained in 
any reportEventNotification() that relates to notifications provisioned from within the network. 

Parameters 

appUIManager : in IpAppUIManagerRef 

If this parameter is set (i.e. not NULL) it specifies a reference to the application interface, which is used for callbacks. If 
set to NULL, the application interface defaults to the interface specified via the setCallbackQ method. 
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Returns 
TpAssignmentlD 

Raises 

TpCommonExc ep t i ons 



8.1 .1 .8 Method disableNotifications() 

This method is used to indicate that the application is not able to receive notifications for which the provisioning has 
been done from within the network, (i.e. these notifications that are NOT set using createNotification() but via, for 
instance, a network management system). After this method is called, no such notifications are reported anymore. 

Parameters 

No Parameters were identified for this method. 

Raises 

TpCommonExc ep t i ons 



8.1 .2 Interface Class IpAppUIManager 



Inherits from: Iplnterface. 

The Generic User Interaction Service manager application interface provides the application callback functions to the 
Generic User Interaction Service. 



«lnterface» 
IpAppUIManager 



userlnteractionAborted (userlnteraction : in TpUlldentifier) : void 

userlnteractionNotificationlnterrupted () : void 

userlnteractionNotificationContinued () : void 

reportEventNotification (userlnteraction : in TpUlldentifier, eventNotificationlnfo : in 
TpUIEventNotificationlnfo, assignmentID : in TpAssignmentlD) : IpAppUIRef 

abortMultipleUserlnteractions (userlnteractionSet : in TpUlldentifierSet) : void 

«new» reportEventReq (userlnteraction : in TpUlldentifier, eventNotificationlnfo : in 
TpUIEventNotificationlnfo, assignmentID : in TpAssignmentlD) : IpAppUIRef 



8.1.2.1 Method userlnteractionAborted() 

This method indicates to the application that the User Interaction service instance has terminated or closed abnormally. 
No further communication will be possible between the User Interaction service instance and application. 
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Parameters 

userlnteraction : in TpUIIdentif ier 

Specifies the interface and sessionID of the user interaction service that has terminated. 



8.1.2.2 Method userlnteractionNotificationlnterrupted() 

This method indicates to the application that all event notifications have been temporarily interrupted (for example, due 
to faults detected). Note that more permanent failures are reported via the Framework (integrity management). 

Parameters 

No Parameters were identified for this method. 



8.1.2.3 Method userlnteractionNotificationContinued() 

This method indicates to the application that event notifications will again be possible. 

Parameters 

No Parameters were identified for this method. 



8.1.2.4 Method reportEventNotification() 

This method notifies the application of an occurred network event which matches the criteria installed by the 
createNotification method. 

Returns: appUI. 

Specifies a reference to the application interface, which implements the callback interface for the new user interaction. 

If the application has previously explicitly passed a reference to the IpAppUI interface using a 
setCallbackWithSessionID() invocation, this parameter may be null, or if supplied must be the same as that provided 
during the setCallbackWithSessionID(). 

Parameters 

userlnteraction : in TpUIIdentif ier 

Specifies the reference to the interface and the sessionID to which the notification relates. 

eventNotif icationlnfo : in TpUIEventNotif icationlnfo 

Specifies data associated with this event. 

assignmentlD : in TpAssignmentlD 

Specifies the assignment id which was returned by the createNotification() method. The application can use assignment 
id to associate events with event specific criteria and to act accordingly. 

Returns 
IpAppUIRef 

8.1.2.5 Method abortMultipleUserlnteractions() 

The service may invoke this method on the IpAppUIManager interface to indicate that a number of ongoing user 
interaction sessions have aborted or terminated abnormally. No further communication will be possible between the 
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application and the user interaction sessions. This may be used for example in the event of service failure and recovery 
in order to instruct the application that a number of sessions have failed. The service shall provide a set of 
TpUIIdentifiers, indicating to the application the interface references and sessionsIDs of the user interaction sessions 
that have aborted. In the case that the service invokes this method and provides an empty set of TpUIIdentifiers, this 
shall be used to indicate that all user interaction sessions previously active on the IpUIManager interface have been 
aborted. 

Parameters 

userlnteractionSet : in TpUIIdentif ierSet 

Specifies the set of interfaces and sessionlDs of the user interaction sessions that have aborted or terminated 
abnormally. The empty set shall be used to indicate that all user interactions have aborted. 

8.1.2.6 Method «new» reportEventReq() 

This asynchronous method sends information to the application from a network event which matches the criteria created 
by the createNotification method. It is used when the service requires a response from the application to indicate that 
the information has been received and processed successfully or not. 

Returns: appUI: 

Specifies a reference to the application interface, which implements the callback interface for the new user interaction. 

Parameters 

userlnteraction : in TpUIIdentif ier 

Specifies the reference to the interface and the sessionID to which the notification relates. 

eventNotif icationlnfo : in TpUIEventNotif icationlnf o 

Specifies data associated with this event. 

assignmentID : in TpAssignmentID 

Specifies the assignment id which was returned by the createNotification() method. The application can use assignment 
id to associate events with event specific criteria and to act accordingly. 

Returns 
IpAppUIRef 



8.1.3 Interface Class I pU I 

Inherits from: IpService. 

The User Interaction Service Interface provides functions to send information to, or gather information from the user. 
An application can use the User Interaction Service Interface independently of other services. 

This interface, or the IpUICall interface, shall be implemented by a Generic User Interaction SCF as a minimum 
requirement. The release() method, and at least one of the sendlnfoReqO or the sendlnfoAndCollectReqQ methods 
shall be implemented as a minimum requirement. 



«lnterface» 
IpUl 



sendlnfoReq (userlnteractionSessionID : in TpSessionID, info : in TpUllnfo, language : in TpLanguage, 
variablelnfo : in TpUl VariablelnfoSet, repeatlndicator : in Tplnt32, responseRequested : in 
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TpUIResponseRequest) : TpAssignmentID 

sendlnfoAndCollectReq (userlnteractionSessionID : in TpSessionID, info : in TpUllnfo, language : in 

TpLanguage, variablelnfo : in TpUIVariablelnfoSet, criteria : in TpUICollectCriteria, responseRequested 
in TpUIResponseRequest) : TpAssignmentID 

release (userlnteractionSessionID : in TpSessionID) : void 

setOriginatingAddress (userlnteractionSessionID : in TpSessionID, origin : in TpString) : void 

getOriginatingAddress (userlnteractionSessionID : in TpSessionID) : TpString 

«new» reportEventRes (userlnteractionSessionID : in TpSessionID, responselnfo : in TpUllnfo) : void 

«new» reportEventErr (userlnteractionSessionID : in TpSessionID, responselnfo : in TpUllnfo, error : in 
TpUIError) : void 



8.1.3.1 Method sendlnfoReqO 

This asynchronous method plays an announcement or sends other information to the user. 

Returns: assignmentlD. 

Specifies the ID assigned by the generic user interaction interface for a user interaction request. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

info : in TpUllnfo 

Specifies the information to send to the user. This information can be: 

- an infoID, identifying pre-defined information to be sent (announcement and/or text); 

- a string, defining the text to be sent; 

- a URL , identifying pre-defined information or data to be sent to or downloaded into the terminal. A URL enables the 
application to utilize dynamic multi-media content by reference; 

- Binary Data, identifying pre-defined information or data to be sent to or downloaded into the terminal. Binary data 
enables the application to utilize dynamic multi-media content directly; 

- a VXML string defines the Voice XML page to execute on the server and interact with the end-user. The VXML page 
execution continues until an <exit/> tag is encountered, which results in a sendInfoRes() callback; 

- a Synthesislnfo structure defines the text to synthesize and how the synthesis should be done. 

language : in TpLanguage 

Specifies the Language of the information to be sent to the user. 

variablelnfo : in TpUIVariablelnfoSet 
Defines the variable part of the information to send to the user. 

repeatlndicator : in Tplnt32 

Defines how many times the information shall be sent to the end-user. A value of zero (0) indicates that the 
announcement shall be repeated until the call or call leg is released or an abortActionReqO is sent. 
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responseRequested : in TpUIResponseRequest 

Specifies if a response is required from the call user interaction service, and any action the service should take. 

Returns 
TpAssignmentID 

Raises 

TpCommonExce.pt ions, PINVALIDSESSIONID, PINVALIDNETWORKSTATE, 
P ILLEGAL ID, P ID NOT FOUND 



8.1.3.2 Method sendlnfoAndCollectReq() 

This asynchronous method plays an announcement or sends other information to the user and collects some information 
from the user. The announcement usually prompts for a number of characters (for example, these are digits or text 
strings such as "YES" if the user's terminal device is a phone). 

Returns: assignmentlD. 

Specifies the ID assigned by the generic user interaction interface for a user interaction request. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

info : in TpUIInfo 

Specifies the ID of the information to send to the user. This information can be: 

- an infoID, identifying pre-defined information to be sent (announcement and/or text); 

- a string, defining the text to be sent; 

- a URL , identifying pre-defined information or data to be sent to or downloaded into the terminal. A URL enables the 
application to utilize dynamic multi-media content by reference; 

- Binary Data, identifying pre-defined information or data to be sent to or downloaded into the terminal. Binary data 
enables the application to utilize dynamic multi-media content directly; 

- a VXML string defines the Voice XML page to execute on the server and interact with the end-user. The VXML page 
execution continues until an <exit/> tag is encountered, which results in a sendInfoAndCollectRes() callback with the 
value of the expr= attribute; 

- a Synthesislnfo structure defines the text to synthesize and how the synthesis should be done. 

language : in TpLanguage 

Specifies the Language of the information to be sent to the user. 

variablelnfo : in TpUIVariablelnfoSet 
Defines the variable part of the information to send to the user. 

criteria : in TpUICollectCriteria 

Specifies additional properties for the collection of information, such as the maximum and minimum number of 
characters, end character, first character timeout and inter-character timeout. This parameter also specifies whether 
voice recognition would be used. 
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responseRequested : in TpUIResponseRequest 

Specifies if a response is required from the call user interaction service, and any action the service should take. For this 
case it can especially be used to indicate e.g. the final request. If P_UI_RESPONSE_REQUIRED is not enabled by the 
application request, the user interaction shall nevertheless return either a sendlnfoAndCollectRes or 
sendlnfoAndCollectErr method to the application in response to this method invocation. 

Returns 
TpAssignmentID 

Raises 

TpCoirunonExceptions, PINVALIDSESSIONID, PINVALIDNETWORKSTATE, 
P_ILLEGAL_ID, PIDNOTFOUND, PILLEGALRANGE, 
P INVALID COLLECTION CRITERIA 



8.1.3.3 Method release() 

This method requests that the relationship between the application and the user interaction object be released. It causes 
the release of the used user interaction resources and interrupts any ongoing user interaction. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction created. 

Raises 

TpCoirunonExceptions , PINVALIDSESSIONID 



8.1.3.4 Method setOriginatingAddress() 

This method sets the originating address property on the user interaction session to be used when sending information to 
the user. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

origin : in TpString 

Specifies the originating address. The originating address description is sent as a TpString. However this field may 
contain E. 164 addresses that the receiving terminal can use to reply to the message. The coding of such an E.164 
address can either be local numbers or international numbers, according to the standard E.164. Examples for a local 
number is "0702106181" and for an international number "+46702106181". 

Raises 

TpCommonExceptions, PINVALIDSESSIONID, PINVALIDNETWORKSTATE, 
P INVALID ADDRESS 
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8.1 .3.5 Method getOriginatingAddress() 

This method gets the originating address property on the user interaction session to be used when sending information 
to the user. If not set with setOriginatingAddress(), the getOriginatingAddress() returns the description that would be 
displayed on the terminal device as the originating address when a message is sent with sendlnfoReqO or 
sendlnfo AndCollectReqO . 

Returns: TpString. 

The address that will be used for a sendlnfoReqO or sendlnfoAndCollectReqO for the originating address. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

Returns 
TpString 

Raises 

TpCommonExceptions, PINVALIDSESSIONID, PINVALIDNETWORKSTATE 



8.1.3.6 Method «new» reportEventRes() 

This asynchronous method indicates the successful completion of a reportEventReq(). 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

responselnfo : in TpUIInfo 

Specifies the information to be returned to the user. 

Raises 

TpCommonExceptions, PINVALIDSESSIONID, PINVALIDNETWORKSTATE, 
PILLEGALID, PIDNOTFOUND 

8.1 .3.7 Method «new» reportEventErr() 

This asynchronous method indicates the unsuccessful completion of a reportEventReq(). 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

responselnfo : in TpUIInfo 

Specifies the information to be returned to the user. 

error : in TpUIError 

Specifies the error which led to the original request failing. 
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Raises 

TpCommonExceptions, PINVALIDSESSIONID, PINVALIDNETWORKSTATE, 
P ILLEGAL ID, P ID NOT FOUND 



8.1 .4 Interface Class IpAppUl 

Inherits from: Iplnterface. 

The User Interaction Application Interface is implemented by the client application developer and is used to handle 
generic user interaction request responses and reports. 




sendlnfoRes (userlnteractionSessionID : in TpSessionID, assignments : in TpAssignmentID, response : in 
TpU I Report) : void 

sendlnfoErr (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, error : in 
TpUIError) : void 

sendlnfoAndCollectRes (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, 
response : in TpUIReport, collectedlnfo : in TpString) : void 

sendlnfoAndCollectErr (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, 
error : in TpUIError) : void 

userlnteractionFaultDetected (userlnteractionSessionID : in TpSessionID, fault : in TpUIFault) : void 



8.1.4.1 Method sendlnfoResO 

This asynchronous method informs the application about the completion of a sendInfoReq(). This response is called 
only if the responseRequested parameter of the sendlnfoReqO method was set to P_UI_RESPONSE_REQUIRED. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the generic user interaction interface for a user interaction request. 

response : in TpUIReport 

Specifies the type of response received from the user. 



8.1.4.2 Method sendlnfoErr() 

This asynchronous method indicates that the request to send information was unsuccessful. This response is called only 
if the responseRequested parameter of the sendlnfoReqO method was set to P_UI_RESPONSE_REQUIRED. In the 
event that a response was not requested and the user interaction was unsuccessful the implementation of the service 
capability must handle the network error, however the error shall not be reported to the application as it requested no 
response. 
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Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignment ID : in TpAssignmentlD 

Specifies the ID assigned by the generic user interaction interface for a user interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 



8.1.4.3 Method sendlnfoAndCollectRes() 

This asynchronous method returns the information collected to the application. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentlD : in TpAssignmentlD 

Specifies the ID assigned by the generic user interaction interface for a user interaction request. 

response : in TpUIReport 

Specifies the type of response received from the user. 

collectedlnfo : in TpString 

Specifies the information collected from the user. 



8.1.4.4 Method sendlnfoAndCollectErr() 

This asynchronous method indicates that the request to send information and collect a response was unsuccessful. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentlD : in TpAssignmentlD 

Specifies the ID assigned by the generic user interaction interface for a user interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

8.1.4.5 Method userlnteractionFaultDetected() 

This method indicates to the application that a fault has been detected in the user interaction. 
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Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the interface and sessionID of the user interaction service in which the fault has been detected. 

fault : in TpUIFault 

Specifies the fault that has been detected. 



8.1 .5 Interface Class IpUICall 

Inherits from: IpUI. 

The Call User Interaction Service Interface provides functions to send information to, or gather information from the 
user (or call party) to which a call leg is connected. An application can use the Call User Interaction Service Interface 
only in conjunction with another service interface, which provides mechanisms to connect a call leg to a user. At 
present, only the Call Control service supports this capability. 

This interface, or the IpUI interface, shall be implemented by a Generic User Interaction SCF as a minimum 
requirement. The minimum required methods of interface IpUI shall be implemented. 



«lnterface» 
IpUICall 



recordMessageReq (userlnteractionSessionID : in TpSessionID, info : in TpUllnfo, criteria : in 
TpUIMessageCriteria) : TpAssignmentID 

deleteMessageReq (usrlnteractionSessionlD : in TpSessionID, messagelD : in Tplnt32) : TpAssignmentID 

abortActionReq (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID) : void 

getMessageReq (userlnteractionSessionID : in TpSessionID, messagelD : in Tplnt32) : TpAssignmentID 



8.1.5.1 Method recordMessageReq() 

This asynchronous method allows the application to send user interaction content to the user followed by the recording 
of a subsequent user input. The recorded message can be played back at a later time with the sendlnfoReqO method. If 
the info parameter is not populated the resource will simply invoke recording at that point in the dialogue. 

Returns: assignmentID. 

Specifies the ID assigned by the generic user interaction interface for a user interaction request. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

info : in TpUllnfo 

Specifies the information to send to the user. This information can be either an ID (for pre-defined announcement or 
text), a text string, or an URL (indicating the information to be sent, e.g. an audio stream). 

criteria : in TpUIMessageCriteria 
Defines the criteria for recording of messages. 
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Returns 

TpA s s i gnmen t I D 

Raises 

TpCommonExceptions, PINVALIDSESSIONID, PINVALIDNETWORKSTATE, 
P ILLEGAL ID, P ID NOT FOUND, P INVALID CRITERIA 



8.1.5.2 Method deleteMessageReq() 

This asynchronous method allows to delete a recorded message. 

Returns: assignmentlD. 

Specifies the ID assigned by the generic user interaction interface for a user interaction request. 

Parameters 

usrlnteractionSessionlD : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

messagelD : in Tplnt32 
Specifies the message ID. 

Returns 

TpA s s i gnmen t I D 

Raises 

TpCommonExceptions, PINVALIDSESSIONID, PILLEGALID, PIDNOTFOUND 



8.1.5.3 Method abortActionReqO 

This asynchronous method aborts a user interaction operation, e.g. a sendlnfoReqO, from the specified call leg. The call 
and call leg are otherwise unaffected. The user interaction call service interrupts the current action on the specified leg. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentlD : in TpAssignmentID 

Specifies the user interaction request to be cancelled. 
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Raises 

TpCommonExceptions, PINVALIDSESSIONID, PINVALIDASSIGNMENTID 



8.1.5.4 Method getMessageReq() 

This asynchronous method allows retrieving the recorded message content from the gateway. This method is applicable 
only to recorded messages. 

Returns: assignmentlD. 

Specifies the ID assigned by the user interaction interface for a user interaction request. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

messagelD : in Tplnt32 
Specifies the message ID. 

Returns 
TpAssignmentID 

Raises 

TpCommonExceptions, PINVALIDSESSIONID, PINVALIDNETWORKSTATE, 
P ILLEGAL ID, P ID NOT FOUND 



8.1 .6 Interface Class IpAppUICall 

Inherits from: IpAppUI. 

The Call User Interaction Application Interface is implemented by the client application developer and is used to handle 
call user interaction request responses and reports. 



«lnterface» 
IpAppUICall 



recordMessageRes (userlnteractionSessionID : in TpSessionID, assignmentlD : in TpAssignmentID, 
response : in TpUIReport, messagelD : in Tplnt32) : void 

recordMessageErr (userlnteractionSessionID : in TpSessionID, assignmentlD : in TpAssignmentID, error : 
in TpUIError) : void 

deleteMessageRes (usrlnteractionSessionlD : in TpSessionID, response : in TpUIReport, assignmentlD : in 
TpAssignmentID) : void 

deleteMessageErr (usrlnteractionSessionlD : in TpSessionID, error : in TpUIError, assignmentlD : in 
TpAssignmentID) : void 

abortActionRes (userlnteractionSessionID : in TpSessionID, assignmentlD : in TpAssignmentID) : void 

abortActionErr (userlnteractionSessionID : in TpSessionID, assignmentlD : in TpAssignmentID, error : in 
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TpUIError) : void 

getMessageRes (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, message 
in TpUllnfo) : void 

getMessageErr (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, error : in 
TpUIError) : void 



8.1.6.1 Method recordMessageRes() 

This method returns whether the message is successfully recorded or not. In case the message is recorded, the ID of the 
message is returned. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call user interaction interface for a user interaction request. 

response : in TpUIReport 

Specifies the type of response received from the device where the message is stored. 

messagelD : in Tplnt32 

Specifies the ID that was assigned to the message by the device where the message is stored. 



8.1.6.2 Method recordMessageErr() 

This method indicates that the request for recording of a message was not successful. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call user interaction interface for a user interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 



8.1.6.3 Method deleteMessageRes() 

This method returns whether the message is successfully deleted or not. 

Parameters 

usrlnteractionSessionlD : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 
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response : in TpUIReport 

Specifies the type of response received from the device where the message was stored. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call user interaction interface for a user interaction request. 



8.1.6.4 Method deleteMessageErr() 

This method indicates that the request for deleting a message was not successful. 

Parameters 

usrlnteractionSessionlD : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call user interaction interface for a user interaction request. 



8.1.6.5 Method abortAction Res() 

This asynchronous method confirms that the request to abort a user interaction operation on a call leg was successful. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call user interaction interface for a user interaction request. 



8.1.6.6 Method abortActionErr() 

This asynchronous method indicates that the request to abort a user interaction operation on a call leg resulted in an 
error. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call user interaction interface for a user interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 
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8.1.6.7 Method getMessageRes() 

This method returns the message content if the message was retrieved successfully. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the user interaction interface for a user interaction request. 

message : in TpUIInfo 

Specifies the UI Information containing the message content information. 

8.1.6.8 Method getMessageErr() 

This method indicates that the request to retrieve a message was not successful. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the user interaction session ID of the user interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the user interaction interface for a user interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 



8.2 Generic User Interaction Administration Interface Classes 
8.2.1 Interface Class IpUIAdminManager 

Inherits from: IpService. 

The Generic User Interaction Administration Manager Service interface is used by applications to manage user 
announcement and recorded messages on the gateway. This Service is represented by the IpUIAdminManager interface 
that interfaces to the service provided by the network. To handle responses and reports, the developer must implement 
IpAppUIAdminManager interface to provide the callback mechanism. 

The application context will ensure that one application does not interfere with the messages of another application. 

The User Interaction Administration Manager Service Interface provides functions to manage the messages. 



«lnterface» 
IpUIAdminManager 



getMessageReq (messagelD : in Tplnt32) : TpAssignmentID 
putMessageReq (info : in TpUIInfo) : TpAssignmentID 
deleteMessageReq (messagelD : in Tplnt32) : TpAssignmentID 



ETSI 



3GPP TS 29.198-05 version 8.0.0 Release 8 46 ETSI TS 129 198-5 V8.0.0 (2009-01) 



getMessageListReq (reset : in TpBoolean) : TpAssignmentID 



8.2.1 .1 Method getMessageReq() 

This asynchronous method allows retrieving the user announcement or recorded message content from the gateway. 

Returns: assignmentlD. 

Specifies the ID assigned by the user interaction administration manager interface for a user interaction request. 

Parameters 

messagelD : in Tplnt32 

Specifies the message ID. 

Returns 
TpAssignmentID 

Raises 

TpCommonExceptions, PINVALIDNETWORKSTATE, PILLEGALID, PIDNOTFOUND 



8.2.1.2 Method putMessageReq() 

This asynchronous method allows putting a user announcement message content onto the gateway. The gateway will 
allocate the messagelD and return it to the application on the putMessageRes() confirmation. 

Returns: assignmentlD. 

Specifies the ID assigned by the generic user interaction administration manager interface for a user interaction request. 

Parameters 

info : in TpUIInfo 

Specifies the information to send to the user. This information can be either an ID (for pre-defined announcement or 
text), a text string, or an URL (indicating the information to be sent, e.g. an audio stream). 

Returns 
TpAssignmentID 

Raises 

TpCommonExceptions, PILLEGALID, PIDNOTFOUND 



8.2.1 .3 Method deleteMessageReq() 

This asynchronous method allows deleting a user announcement or recorded message. 
Returns: assignmentlD. 
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Specifies the ID assigned by the generic user interaction administration manager interface for a user interaction request. 

Parameters 

messagelD : in Tplnt32 

Specifies the message ID. 

Returns 
TpAssignmentlD 

Raises 

TpCommonExceptions, PILLEGALID, PIDNOTFOUND 

8.2.1.4 Method getMessagel_istReq() 

This asynchronous method allows the application to retrieve a list of Message Ids for all its recorded messages or user 
announcements. 

Returns: assignmentlD. 

Specifies the ID assigned by the user interaction administration manager interface in order to correlate the response. 

Parameters 

reset : in TpBoolean 

TRUE: Indicates that the application intends to obtain the list of messages starting from the beginning. 

FALSE: Indicates that the application requests the next part of the list that has not (yet) been obtained since the last call 
to this method with this parameter set to TRUE. 

The first time this method is invoked, reset shall be set to TRUE. Following the receipt of a final indication in the 
getMessageListRes(), for the next call to this method reset shall be set to TRUE. P_TASK_REFUSED may be thrown if 
these conditions are not met. 

The state information for returning the list will be stored relative to the application context, therefore only one 
enumeration per application context can be active at a time. 

Returns 
TpAssignmentlD 

Raises 

TpCommonExceptions , PINVALID NETWORKSTATE 

8.2.2 Interface Class IpAppUIAdminManager 

Inherits from: Iplnterface. 

The User Interaction Administration Manager Application Interface is implemented by the client application and is used 
to handle administration user interaction request responses and reports. 



«lnterface» 
IpAppUIAdminManager 
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getMessageRes (assignmentID : in TpAssignmentID, message : in TpUllnfo) : void 

getMessageErr (assignmentID : in TpAssignmentID, error : in TpUIError) : void 

deleteMessageRes (response : in TpUIReport, assignmentID : in TpAssignmentID) : void 

deleteMessageErr (error : in TpUIError, assignmentID : in TpAssignmentID) : void 

putMessageRes (assignmentID : in TpAssignmentID, messagelD : in Tplnt32) : void 

putMessageErr (assignmentID : in TpAssignmentID, error : in TpUIError) : void 

getMessageListRes (assignmentID : in TpAssignmentID, messagelDList : in TpMessagelDList, final : in 
TpBoolean) : void 

getMessageListErr (assignmentID : in TpAssignmentID, error : in TpUIError) : void 



8.2.2.1 Method getMessageRes() 

This method returns the message content if the message was retrieved successfully. 

Parameters 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the user interaction administration manager interface for a user interaction request. 

message : in TpUllnfo 

Specifies the UI Information containing the message content information. 



8.2.2.2 Method getMessageErr() 

This method indicates that the request to retrieve a message was not successful. 

Parameters 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the user interaction administration manager interface for a user interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

8.2.2.3 Method deleteMessageRes() 

This method indicates that the request to delete a message was successful. 

Parameters 

response : in TpUIReport 

Specifies the type of response received from the device where the message was stored. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the user interaction administration manager interface for a user interaction request. 
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8.2.2.4 Method deleteMessageErr() 

This method indicates that the request to delete a message was not successful. 

Parameters 

error : in TpUIError 

Specifies the error which led to the original request failing. 

assignment ID : in TpAssignmentlD 

Specifies the ID assigned by the user interaction administration manager interface for a user interaction request. 

8.2.2.5 Method putMessageRes() 

This asynchronous method confirms that the request to put the message content was successful. 

Parameters 

assignmentlD : in TpAssignmentlD 

Specifies the ID assigned by the user interaction administration manager interface for a user interaction request. 

messagelD : in Tplnt32 

Specifies the message ID that was allocated by the gateway. 

8.2.2.6 Method putMessageErr() 

This asynchronous method indicates that the request to put the message content resulted in an error. 

Parameters 

assignmentlD : in TpAssignmentlD 

Specifies the ID assigned by the user interaction administration manager interface for a user interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

8.2.2.7 Method getMessagel_istRes() 

This asynchronous method returns the result of a getMessageListReqO method. Whether there are still more messages 
that can be listed yet will be indicated with the final parameter. 

Parameters 

assignmentlD : in TpAssignmentlD 

Specifies the ID assigned by the user interaction administration manager interface in order to correlate with the request. 

messagelDList : in TpMessagelDList 

Specifies the list of MessagelDs returned by the SCF. 
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final : in TpBoolean 

Indication whether the returned list is the final part of the complete list (TRUE) or if there are still parts of the list to 
retrieve (FALSE). 

8.2.2.8 Method getMessagel_istErr() 

This asynchronous method indicates that the request to list the messagelDs was not successful. 

Parameters 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the user interaction administration manager interface in order to correlate with the request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

9 State Transition Diagrams 

9.1 Generic and Call User Interaction State Transition 
Diagrams 

9.1 .1 State Transition Diagrams for IpUIManager 
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Figure : Application view on the UI Manager 
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9.1.1.1 Active State 

In this state a relation between the Application and a User Interaction Service Capability Feature (Generic User 
Interaction or Call User Interaction) has been established. The application is now able to request creation of UI and/or 
UlCall objects. 

9.1 .1 .2 Notification Terminated State 

When the UI manager is in the Notification terminated state, events requested with 

createNotification()/enableNotifications() will not be forwarded to the application. There can be multiple reasons for 
this: for instance it might be that the application receives more notifications than defined in the Service Level 
Agreement. Another example is that the SCS has detected it receives no notifications from the network due to e.g. a link 
failure. In this state no requests for new notifications will be accepted. 

9.1 .2 State Transition Diagrams for IpUl 

The state transition diagram shows the application view on the User Interaction object. 
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Figure : Application view on the UI object 

9.1.2.1 Active State 

In this state the UI object is available for requesting messages to be sent to the network. 

In case a fault is detected on the user interaction (e.g. a link failure to the IVR system), userInteractionFaultDetected() 
will be invoked on the application and an error will be reported on all outstanding requests. 

9.1 .2.2 Release Pending State 

A transition to this state is made when the Application has indicated that after a certain message no further messages 
need to be sent to the end-user. There are, however, still a number of messages that are not yet completed. When the last 
message is sent or when the last user interaction has been obtained, the UI object is destroyed. 

In case the final request failed or the application requested to abort the final request, a transition is made back to the 
Active state. 

In case a fault is detected on the user interaction (e.g. a link failure to the IVR system), userInteractionFaultDetected() 
will be invoked on the application and an error will be reported on all outstanding requests. 
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9.1.2.3 Finished State 

In this state the user interaction has ended. The application can only release the UI object. Note that the application has 
to release the object itself as good Object Oriented practice requires that when an object is created on behalf of a certain 
entity, this entity is also responsible for destroying it when the object is no longer needed. 

9.1 .3 State Transition Diagrams for IpUICall 

The state transition diagram shows the application view on the Call User Interaction object. 




In slate Finished a iimer mechanism 

should prevent that the object keeps 

expires, the object should be destroyed 

be reported to the application. 



Figure : Application view on the UlCall object 



9.1.3.1 Active State 



In this state a UlCall object is available for announcements to be played to an end-user or obtaining information from 
the end-user. 

When the application de-assigns the related Call or CallLeg object, a transition is made to the Finished state. However, 
all requested announcements will continue, even when the application releases the UlCall object. 

When the related call or call leg is terminated due to some reason, a transition is made to the Finished state, the 
operation userInteractionFaultDetected() will be invoked on the application and an error will be reported on all 
outstanding requests. 

In case a fault is detected on the user interaction (e.g. a link failure to the IVR system), userInteractionFaultDetected() 
will be invoked on the application and an error will be reported on all outstanding requests. 

9.1 .3.2 Release Pending State 

A transition to this state is made when the Application has indicated that after a certain announcement no further 
announcements need to be played to the end-user. There are, however, still a number of announcements that are not yet 
completed. When the last announcement is played or when the last user interaction has been obtained, the UlCall object 
is destroyed. In case the final request failed or the application requested to abort the final request, a transition is made 
back to the Active state. 

When the application de-assigns the related Call or CallLeg object, the UlCall object is destroyed. However, all 
requested announcements will continue. 

When the related call or call leg is terminated due to some reason, a transition is made to the Finished state, the 
operation userInteractionFaultDetected() will be invoked on the application and an error will be reported on all 
outstanding requests. 
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In case a fault is detected on the user interaction (e.g. a link failure to the IVR system), userInteractionFaultDetected() 
will be invoked on the application and an error will be reported on all outstanding requests. 

9.1.3.3 Finished State 

In this state the user interaction has ended. The application can only release the UlCall object. Note that the application 
has to release the object itself as good Object Oriented practice requires that when an object is created on behalf of a 
certain entity, this entity is also responsible for destroying it when the object is no longer needed. 

9.2 Generic User Interaction Administration State Transition 
Diagrams 

9.2.1 State Transition Diagrams for IpUIAdminManager 
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Figure : State Transition Diagram for User Interaction Administration 

9.2.1.1 Active State 

In this state, a relation between the Application and the Generic User Interaction Administration Service Capability 
Feature has been established. It allows the application to make specific requests of the service. 
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1 Service Properties 

10.1 User Interaction Service Properties 

The following table lists properties relevant for the User Interaction API. 



Property 


Type 


Description 


P INFO TYPE 


INTEGER SET 


Specifies whether the UI SCS supports text or URLs etc. Allowed values are 
defined by TpUIInfoType. 


P_SPEECH RECOGNITION SUPPORTED 


BOOLEAN 


Value: TRUE when the speech recognition features are supported. 



The previous table lists properties related to capabilities of the SCS itself. The following table lists properties that are 
used in the context of the Service Level Agreement, e.g. to restrict the access of applications to the capabilities of the 
SCS. 



Property 


Type 


Description 


P SERVICE CODE 


INTEGER SET 


Specifies the service codes that may be used for notification 
requests. 


P NOTIFICATION ADDRESS RANGES 


XML ADDRESS RANGE SET 


Indicates for which numbers notifications may be set. More than 
one range may be present. 


P PRIORITY 


INTEGER SET 


This data type defines the probability of communication completion 
with the media resource (under network congestion). A list of values 
may be offered by the SCF. A value of indicates no special 
treatment (default). The other values of this data type are region 
specific. For example, a priority value between 1, 2, 3, ..., n 
indicates special treatment, where 1 may be the highest priority and 
n the lowest priority other than no special treatment. 



11 



Data Definitions 



The following data types referenced in this clause are defined in 3GPP TS 29.198-4: 

TpCall Identifier 
TpMultiPartyCall Identifier 
TpCallLegldentif ier 

All other data types referenced but not defined in this clause are common data definitions which may be found in 3GPP 
TS 29.198-2. 



11.1 TpUIFault 



Defines the cause of the UI fault detected. 



Name 


Value 


Description 


P UI FAULT UNDEFINED 





Undefined 


P UI CALL_ENDED 


l 


The related Call object has been terminated. Therefore, the UlCall object is also terminated. No 
further interaction is possible with this object. 



11.2 IpUl 

Defines the address of an IpUI Interface. 
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11.3 IpUIRef 

Defines a Reference to type IpUI. 

11.4 IpAppUl 



Defines the address of an IpAppUl Interface. 



11.5 IpAppUIRef 

Defines a Reference to type IpAppUl. 

11.6 IpAppUl Manager 

Defines the address of an IpAppUIManager Interface. 

11.7 IpAppUIManagerRef 

Defines a Reference to type IpAppUIManager . 

11.8 TpUICallldentifier 

Defines the Sequence of Data Elements that unambiguously specify the UlCall object. 



Structure Element Name 


Structure Element Type 


Structure Element Description 


UICallRef 


IpUICallRef 


This element specifies the interface reference for the UlCall object. 


UserlnteractionSessionID 


TpSessionID 


This element specifies the User Interaction session ID. 



11.9 TpUICollectCriteria 



Defines the Sequence of Data Elements that specify the additional properties for the collection of information, 
such as the end character, first character timeout, inter-character timeout, and maximum interaction time. The 
CollectMode element defines the type of data that is to be collected. DTMF and Voice Recognition can be used 
separately or in combination. The P_SPEECH_RECOGNITION_SUPPORTED property defines whether the voice 
recognition features are supported. 



Structure Element Name 


Structure Element Type 


MinLength 


Tplnt32 


MaxLength 


Tplnt32 


EndSequence 


TpString 


StartTimeout 


TpDuration 


InterCharTimeout 


TpDuration 


CollectMode 


TpUI CollectMode 


RecognitionCriteria 


TpUIRecognitionCriteria 



The structure elements specify the following criteria: 



MinLength: 
MaxLength : 



Defines the minimum number of characters (e.g. digits) to collect. Applies to DTMF 
collection and voice recognition. 

Defines the maximum number of characters (e.g. digits) to collect. Applies to DTMF 
collection and voice recognition. 
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EndSequence : Defines the character or characters which terminate an input of variable length, e.g. phone 

numbers. Applies to DTMF collection only. 

StartTimeout : specifies the value for the first character time-out timer. The timer is started when the 

announcement has been completed or has been interrupted. The user should enter the start 
of the response (e.g. first digit) before the timer expires. If the start of the response is not 
entered before the timer expires, the input is regarded to be erroneous. After receipt of the 
start of the response, which may be valid or invalid, the timer is stopped. Applies to DTMF 
collection and voice recognition. 

InterCharTimeOut : specifies the value for the inter-character time-out timer. The timer is started when a 

response (e.g. digit) is received, and is reset and restarted when a subsequent response is 
received. The responses may be valid or invalid, the announcement has been completed or 
has been interrupted. Applies to DTMF collection only. 

CollectMode : Defines the type of collection to do. Applies to DTMF collection and voice recognition. 

The default is DTMF collection only. 

RecognitionCriteria : Defines the criteria for voice recognition. 



Input is considered successful if the following applies: 
If the EndSequence is not present (i.e. an empty string): 

when the InterCharTimeOut timer expires; or 

when the number of valid digits received equals the MaxLength. 
If the EndSequence is present: 

when the InterCharTimeOut timer expires; or 

when the EndSequence is received; or 

when the number of valid digits received equals the MaxLength. 

In the case the number of valid characters received is less than the MinLength when the InterCharTimeOut timer 
expires or when the EndSequence is received, the input is considered erroneous. 

The collected characters (including the EndSequence) are sent to the client application when input has been 
successful. 
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11.10 TpUIError 



Defines the UI error codes. 



Name 


Value 


Description 


P UI ERROR UNDEFINED 





Undefined error. 


P UI ERROR ILLEGAL INFO 


l 


The specified information (Infold, InfoData, or InfoAddress) is invalid. 


P UI ERROR ID NOT FOUND 


2 


A legal Infold is not known to the User Interaction service. 


P UI ERROR RESOURCE UNAVAILABLE 


3 


The information resources used by the User Interaction service are unavailable, e.g. 
due to an overload situation. 


P UI ERROR ILLEGAL RANGE 


4 


The values for minimum and maximum collection length are out of range. 


P UI ERROR IMPROPER USER RESPONSE 


5 


Improper user response. 


P UI ERROR ABANDON 


6 


The specified leg is disconnected before the send information completed. 


P UI ERROR NO OPERATION ACTIVE 


7 


There is no active User Interaction for the specified leg. Either the application did not 
start any User Interaction or the User Interaction was already finished when the 

abortActionReq ( ) was called. 


P UI ERROR NO SPACE AVAILABLE 


8 


There is no more storage capacity to record the message when the 
recordMessageReq ( ) operation was called. 


P UI ERROR RESOURCE TIMEOUT 


9 


The request has been accepted by the resource but it did not report a result. 



The call User Interaction object will be automatically de-assigned if the error P_UI_ERROR_AB ANDON is reported, as a 
corresponding call or call leg object no longer exists. 



11.11 TpUIEventCriteria 



Defines the Sequence of Data Elements that specify the additional criteria for receiving a UI notification 



Structure Element 
Name 


Structure Element 
Type 


Description 


OriginatingAddress 


TpAddressRange 


Defines the originating address for which the notification is requested. 


DestinationAddress 


TpAddr e s s Range 


Defines the destination address or address range for which the notification is requested. 


ServiceCode 


TpString 


Defines a 2-digit code indicating the UI to be triggered. The value is operator specific. 



11.12 TpUIEventCriteriaResultSet 

Defines a set of TpUIEventCriteriaResult. 

11.13 TpUIEventCriteriaResult 

Defines a sequence of data elements that specify a requested event notification criteria with the associated 
assignmentlD. 



Structure Element Name 


Structure Element Type 


Structure Element Description 


Event Criteria 


TpUIEventCriteria 


The event criteria that were specified by the application. 


AssignmentlD 


Tplnt32 


The associated assignmentlD. This can be used to disable the notification. 
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11.14 TpUIEventlnfoDataType 

Defines the type of the dataString parameter in the method userlnteractionEventNotify. 



Name 


Value 


Description 


P UI_EVENT_DATA_TYPE_UNDEFINED 





Undefined (e.g. binary data) 


P UI EVENT DATA TYPE UNSPECIFIED 


i 


Unspecified data 


P_UI_EVENTJDATA TYPE TEXT 


2 


Text 


P UI EVENT DATA TYPE USSD DATA 


3 


USSD data starting with coding scheme 



11.15 TpUlldentifier 



Defines the Sequence of Data Elements that unambiguously specify the UI object 



Structure Element Name 


Structure Element Type 


Structure Element Description 


UIRef 


IpUIRef 


This element specifies the interface reference for the UI object. 


UserlnteractionSessionID 


TpSessionID 


This element specifies the User Interaction session ID. 



11.16 TpUlldentifierSet 

Defines a Numbered Set of Data Elements of TpUlldentifier. 



11.17 Tpllllnfo 



Defines the Tagged Choice of Data Elements that specify the information to send to the user. 





Tag Element Type 






TpUIInfoType 






Tag Element Value 


Choice Element Type 


Choice Element Name 


P UI INFO ID 


Tplnt32 


Infold 


P UI INFO DATA 


TpString 


Inf oData 


P_UI_INFO_ADDRESS 


TpURL 


Inf oAddress 


P UI INFO BIN DATA 


TpOctetSet 


Inf oBinData 


P UI INFO UUENCODED 


TpString 


InfoUUEncData 


P UI INFO MIME 


TpOctetSet 


InfoMimeData 


P UI INFO WAVE 


TpOctetSet 


Inf oWaveData 


P UI INFO AU 


TpOctetSet 


InfoAuData 


P UI INFO VXML 


TpString 


InfoVXMLData 


P UI INFO SYNTHESIS 


TpUISynthesisInfoData 


InfoSynthData 



The choice elements represent the following: 

InfoID: 



Inf oData : 



defines the ID of the user information script or stream to send to an end-user. The values of 
this data type are operator specific. 

defines the data to be sent to an end-user's terminal. The data is free-format and the 
encoding is depending on the resources being used.. 
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Inf oAddress : 

Inf oBinData : 

Inf oUUEncData : 
Inf oMimeData : 
Inf oWaveData : 
Inf oAuData : 
Inf oVXMLData : 

Inf oSynthData : 



defines the URL of the text, voice application script or stream to be either sent to an end- 
user's terminal or invoked in the network in order to carry out the interaction dialogue. 

defines the binary data to be sent to an end-user's terminal. The data is a free-format, 8-bit 
quantity that is guaranteed not to undergo any conversion when transmitted. 

defines the UUEncoded data to be sent to an end-user's terminal. 

defines the MIME data to be sent to an end-user's terminal. 

defines the WAVE data to be sent to an end-user's terminal. 

defines the AU data to be sent to an end-user's terminal. 

defines the TpString that describes the VXML (Voice XML) page that is sent to the server 
for execution and interaction with the end-user. See http ://w w w . w3 . org/TR/2000/NOTE- 
voicexml-20000505/ for more information. 

defines the TpUISynthesisInfoData that describes the content and how the speech synthesis 
will be done. 

InfoSynthData allows the application to utilize the fundamental speech synthesis 
capabilities of the server without dependency VXML, while Info VXMLData allows the 
application to send a complex VXML program (including call control, flow control, 
dynamic content, menuing, etc) to the server for execution with little change to the OSA 
application itself. 



11.18 TpUllnfoType 

Defines the type of the information to be sent to the user. 



Name 


Value 


Description 


P UI INFO ID 





The information to be send to an end-user consists of an ID 


P UI INFO DATA 


i 


The information to be send to an end-user consists of a data string 


P_UI_INFO_ADDRESS 


2 


The information to be send to an end-user consists of a URL. 


P UI INFO BIN DATA 


3 


The information to be sent to an end-user consists of an 8 bit binary data set. 


P UI INFO UUENCODED 


4 


The information to be sent to an end-user consists of UUEncoded data. 


P UI INFO MIME 


5 


The information to be sent to the end-user consists of MIME encoded data. 


P UI INFO WAVE 


6 


The information to be sent to the end-user is .wav waveform data. 


P UI INFO AU 


7 


The information to be sent to the end-user is .au audio data. 


P UI INFO VXML 


8 


The information to be sent to the end-user is controlled by this VXML. 


P UI INFO SYNTHESIS 


9 


The information to be sent to an end-user is synthesized from text. 



11.19 TpUIMessageCriteria 



Defines the Sequence of Data Elements that specify the additional properties for the recording of a message. 



Structure Element Name 


Structure Element Type 


EndSequence 


TpString 


MaxMessageTime 


TpDuration 


MaxMessageSize 


Tplnt32 



The structure elements specify the following criteria 

EndSequence : 



Defines the character or characters which terminate an input of variable length, e.g. phone 
numbers. 
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MaxMessageTime : specifies the maximum duration in seconds of the message that is to be recorded. 

MaxMessageSize : If this parameter is non-zero, it specifies the maximum size in bytes of the message that is 

to be recorded. 



11.20 TpU I Report 

Defines the UI reports if a response was requested. 



Name 


Value 


Description 


P_UI REPORT UNDEFINED 





Undefined report 


P_UI_REPORT_INFO_SENT 


i 


Confirmation that the information has been sent 


P UI_REPORT_INFO_COLLECTED 


2 


Information collected., meeting the specified criteria. 


P UI REPORT_NO_INPUT 


3 


No information collected. The user immediately entered the delimiter character. 
No valid information has been returned 


P UI REPORT TIMEOUT 


4 


No information collected. The user did not input any response before the input timeout 

expired 


P UI_REPORTJYIESSAGE STORED 


5 


A message has been stored successfully 


P UI_REPORT_MESSAGE_NOT_STORED 


6 


The message has not been stored successfully 


P UI REPORT MESSAGE DELETED 


7 


A message has been deleted successfully 


P UI_REPORT_MESSAGE NOT DELETED 


8 


A message has not been deleted successfully 



11.21 TpUIResponseRequest 

Defines the situations for which a response is expected following the User Interaction. 



Name 


Value 


Description 


P UI RESPONSE REQUIRED 


l 


The User Interaction Call shall send a response when the request has completed. 


P UI LAST ANNOUNCEMENT IN A_ROW 


2 


This is the final announcement within a sequence. It might, however, be that 
additional announcements will be requested at a later moment. The User Interaction 
Call service may release any used resources in the network. The UI object will not be 

released. 


P UI FINAL REQUEST 


4 


This is the final request. The UI object will be released after the information has been 
presented to the user. 



This parameter represents a so-called bitmask, i.e. the values can be added to derived the final meaning. 

1 1 .22 TpU ITargetObjectType 

Defines the type of object where User Interaction should be performed upon. 
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Name 


Value 


Description 


P UI_TARGET_OBJECT CALL 





User-interaction will be performed on a complete Call. 


P UIJTARGETJDBJECT MULTI_PARTY CALL 


i 


User-interaction will be performed on a complete Multi-party Call. 


P UI_TARGET_OBJECT CALL LEG 


2 


User-interaction will be performed on a single Call Leg. 

The media of this call leg should be detached at the moment any user 

interaction is done. 



11.23 TpUITargetObject 



Defines the Tagged Choice of Data Elements that specify the object to perform User Interaction on. 





Tag Element Type 






TpUITargetOb j ectType 





Tag Element Value 


Choice Element Type 


Choice Element Name 


P_UI_TARGET_OBJECT_CALL 


TpCall Identifier 


Call 


P_UI_TARGET_OBJECT_MULTI_PARTY_CALL 


TpMultiPartyCall Identifier 


MultiPartyCall 


P_UI_TARGET_OBJECT_CALL_LEG 


TpCallLegldentif ier 


CallLeg 



11.24 TpUIVariablelnfo 



Defines the Tagged Choice of Data Elements that specify the variable parts in the information to send to the 
user. 





Tag Element Type 






TpUIVariablePartType 





Tag Element Value 


Choice Element Type 


Choice Element Name 


P UI VARIABLE PART INT 


Tplnt32 


VariablePart Integer 


P UI VARIABLE PART ADDRESS 


TpString 


Variable Part Address 


P UI VARIABLE_PART TIME 


TpTime 


VariablePartTime 


P UI VARIABLE_PART_DATE 


TpDate 


VariablePartDate 


P UI VARIABLE PART PRICE 


TpPrice 


VariablePart Price 



11.25 TpUIVariablelnfoSet 

Defines a Numbered Set of Data Elements of TpUIVariablelnfo. 

1 1 .26 TpUIVariablePartType 

Defines the type of the variable parts in the information to send to the user. 



Name 


Value 


Description 


P UI VARIABLE PART INT 





Variable part is of type integer 


P UI VARIABLE PART ADDRESS 


i 


Variable part is of type address 


P UI VARIABLE_PART TIME 


2 


Variable part is of type time 


P UI VARIABLE_PART_DATE 


3 


Variable part is of type date 


P UI VARIABLE PART PRICE 


4 


Variable part is of type price 
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1 1 .27 TpUIEventNotificationlnfo 

DefinestheSequen.ee of Data Elements that specify a UI event notification. 



Structure Element Name 


Structure Element Type 


Structure Element Description 


OriginatingAddress 


TpAddress 


Defines the originating address. 


DestinationAddress 


TpAddress 


Defines the destination address. 


ServiceCode 


TpString 


Defines a 2-digit code indicating the UI to be triggered. 
The value is operator specific. 


DataTypelndication 


TpUIEventlnfoDataType 


Identifies the type of contents in UIEventData 


UIEventData 


TpOctetSet 


Freely defined data according to the network policy, 
e.g 7 bit USSD encoded 



1 1 .28 TpUISynthesislnfoData 



Defines the Sequence of Data Elements that specify the information to use in generating the desired effects on 
the generated voice. The speech synthesis parameters or processing tags will be interpreted as hints and may be ignored 
by the speech synthesis engine. Note that the language is specified on the sendlnfoReqO and sendlnfoAndCollectReqO 
method calls. 



The TextData field may contain the following tags to affect the processing of the text. The <break> tag specifies a 
timing pause. The <emp> tag specifies an emphasis on a word or phrase. 



<break size="milliseconds" > 



<emp>A word</emp; 



// specifies a timing pause in the 
// middle of the text in milliseconds 
// apply emphasis to a word or words 



Structure Element Name 


Structure Element Type 


Structure Element Description 


SpeakerGender 


TpUI Synthes i sGender 


Defines the gender of the speaker. 


SpeakerAge 


TpUISynthesisAge 


Defines the age of the speaker. 


SpeakerRate 


TpUI Synthes isRate 


Defines the rate of the speaker. 


SpeakerRange 


TpUI Synthes i sRange 


Defines the range of the speaker. 


TextData 


TpString 


Defines the text to synthesize into speech. 


WordOverrideSet 


TpUIWordOverrideSet 


Defines the pronunciation overrides. 



1 1 .29 TpUISynthesisGender 

Defines the UI reports if a response was requested. 



Name 


Value 


Description 


P UI GENDER MALE 





Male 


P UI GENDER FEMALE 


l 


Female 



11.30 TpUISynthesisAge 

Defines the UI reports if a response was requested. 
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Name 


Value 


Description 


P UI AGE CHILD 





Child voice 


P UI_AGE_YOUNG_ADULT 


i 


Young adults voice 


P UI_AGE_ADULT 


2 


Adult voice 


P UI AGE_OLDER_ADULT 


3 


Older adult voice 



11.31 TpUISynthesisRate 

Defines the rate of the speech. 



Name 


Value 


Description 


P UI RATE SLOW 





Slow speech rate 


P_UI_RATE_AVERAGE 


l 


Average speech rate 


P UI RATE FAST 


2 


Fast speech rate 



1 1 .32 TpUISynthesisRange 

Defines the range or liveliness of the speech. 



Name 


Value 


Description 


P_UI_RANGE_CALMER 





Very Calm or monotone speech 


P UI_RANGE_CALM 


i 


Moderately calm speech 


P UI_RANGE_AVERAGE 


2 


Average speech 


P UI_RANGE_EXCITED 


3 


Moderately excited or lively speech 


P UI_RANGE_MORE_EXCITED 


4 


Excited or lively speech 



1 1 .33 TpU I WordOverrideSet 

Defines a Numbered Set of Data Elements of TpUIWordOverride. 

11.34 TpUIWordOverride 

Defines the Sequence of Data Elements that specify the information to use in overriding the default 
pronunciation of a word. 



Structure Element Name 


Structure Element Type 


Structure Element Description 


Spelling 


TpString 


Defines the spelling of the word override. 


PronounceType 


TpUI PronounceType 


Defines the type of pronunciation syntax. 


PronounceAs 


TpString 


Defines how the spelling field should be pronounced. 



11.35 TpUIPronounceType 



Defines the pronunciation type. 

The International Phonetic Alphabet (IP A) representation can be used to specify pronunciations. For more information 

see: 

http://www2.arts.gla.ac.uk/IPA/ipachart.html 
http://www.unicode.org/charts/PDF/U0250.pdf 
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Also, simple sound-alike replacements can be used, such as "I triple E" for IEEE. 



Name 


Value 


Description 


P UI PRONOUNCE I PA 





The IPA pronunciation type 


P_UI PRONOUNCE SOUNDSLIKE 


i 


The simple sounds like replacement type 



11.36 TpUICollectMode 

Defines the type of collection. 



Name 


Value 


Description 


P UI COLLECT_MODE_DTMF 





Collect DTMF digits only 


P UI COLLECT_MODE_VOICE 


l 


Collect Voice recognized data 


P UI COLLECT_MODE_DTMFANDVOICE 


2 


Collect both DTMF digits and voice recognized data 



11.37 TpUIRecognitionCriteria 



Defines the Sequence of Data Elements that specify the additional properties for the collection of information 
in the form of voice recognition according to the specified grammar. 



Structure Element Name 


Structure Element Type 


SpeakerlD 


TpUIRecognitionSpeakerlD 


Properties 


TpUIRecognitionPropertySet 


Grammar 


TpUIRecognitionGrammar 



The structure elements specify the following criteria: 

SpeakerlD: Defines the user identifier associating a user with a speech profile known to the recognition engine, 

which provides a hint for better quality. 

Properties: Defines the properties set for additional information to the speech recognition engine. 

Grammar: Defines the syntax of the language to be recognized. 

1 1 .38 TpUIRecognitionSpeakerlD 

Defines a user identifier string that identifies the speaker and is a hint to whose voice is to be recognized. 

11.39 TpUIRecognitionPropertySet 

Defines a Numbered Set of Data Elements of TpUIRecognitionProperty. 

11.40 TpUIRecognitionProperty 

Defines the Sequence of Data Elements that specify the additional properties for the recognition engine. The 
TpUIRecognitionProperty is a hint to the recognition engine on how it should interpret the input. 



Structure Element Name 


Structure Element Type 


Proper tyName 


TpString 


Proper tyValue 


TpString 



The structure elements specify the following criteria: 
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PropertyName: Defines the name of the property. 

PropertyValue: Defines the value of the property. 

The defined properties are: 

P_RECOGNITION_PROPERTY_CONFIDENCE_LEVEL - The speech recognition confidence level, a float value in 
the range of 0.0 to 1.0. Results are rejected when the recognitions engine's confidence in its interpretation is below this 
threshold. A value of 0.0 means minimum confidence is needed for a recognition, and a value of 1 .0 requires maximum 
confidence. The default value is 0.5. 

P_RECOGNITION_PROPERTY_SENSITIVITY - Set the sensitivity level. A value of 1.0 means that it is highly 
sensitive to quiet input. A value of 0.0 means it is least sensitive to noise. The default value is 0.5. 

P_RECOGNITION_PROPERTY_SPEEDVSACCURACY - A hint specifying the desired balance between speed vs. 
accuracy. A value of 0.0 means fastest recognition. A value of 1.0 means best accuracy. The default is value 0.5. 

P_RECOGNITION_PROPERTY_COMPLETE_TIMEOUT - The speech timeout value to use when an active grammar 
is matched. 



11.41 TpUIRecognitionGrammar 



Defines a string that consists of an inline grammar that specifies the syntax of the speech to be recognized. The format 
of this string is based on a subset of the Voice XML 1 .0 grammar element tag. The in-line grammar text must be 
enclosed within <grammar> ...</grammar> element tags. The contents of the grammar specifies the allowable input that 
the voice recognition will accept. The Voice XML grammar specifies the set of utterances that a user may speak to 
perform an action and specifies the corresponding string value for the result. 

The following table describes the features that provide a language for describing context-free grammars. 

Feature Purpose 

word or words (terminals, tokens) need not be quoted 

[x] optional x 

(...) Grouping 

x {value text} arbitrary value text may be associated with x 

x* or more occurrences of x 

x+ 1 or more occurrences of x 

x y z ... a sequence of x then y then z then ... 

x I y I z I ... a set of alternatives of x or y or z or ... 

<rule> rule names (non-terminals) are enclosed in <> 

<rule> = x; a private rule definition 

public <rule> = x; a public rule definition 

The format of the grammar tag is: 

<grammar> grammar content < /grammar > 

The grammar defines a possible set of utterances. The text of the utterance itself is used as the value, if the value text is 
not explicitly specified with { value } . 

This form is particularly convenient for expressing simple lists of alternative ways of saying the same thing, for 
example: 

< grammar > 

[please] help [me] [please] | [please] I (need | want) help [please] 
< /grammar > 

<grammar> 

hamburger | burger {hamburger} | (chicken [sandwich] ) {chicken} 
< /grammar > 
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In the first example, any of the ways of saying "help" result in a valid response. In the second example, the user may 
say "hamburger" or "burger" and the response will be given the value "hamburger", or the user may say "chicken" or 
"chicken sandwich" and the result will be given the value "chicken". 

If the grammar can not be matched, then a sendlnfoAndCollectErr will result, with a 
P_IMPROPER_USER_RESPONSE. 

For a better description and further examples of in-line grammar creation see [4]. 



11.42 TpMessagelDList 



This data type defines a Numbered List of Data Elements of type Tplnt32. 



12 Exception Classes 

The following are the list of exception classes which are used in this interface of the API. 



Name 


Description 


P ILLEGAL ID 


Information id specified is invalid 


P ID_NOT_FOUND 


Information id is unknown 


P ILLEGAL_RANGE 


The values for minimum and maximum collection length are out of 
range. 


P INVALID COLLECTION_CRITERIA 


Invalid collection criteria specified 



Each exception class contains the following structure: 



Structure Element Name 


Structure Element Type 


Structure Element Description 


Extralnf ormation 


TpString 


Carries extra information to help identify the source of the 
exception, e.g. a parameter name 
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Annex A (normative): 

OMG IDL Description of User Interaction SCF 

The OMG IDL representation of this interface specification is contained in text files (ui_data.idl and ui_interfaces.idl 
contained in archive 2919805V800IDL.ZIP) which accompany the present document. 
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Annex B (informative): 

WSDL Description of User Interaction SCF 

The W3C WSDL representation of this interface specification is contained in zip file 2919805V800WSDL.ZIP, which 
accompanies the present document. 
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Annex C (informative): 

Java™ API Description of the User Interaction SCF 

The Java™ API realisation of this interface specification is produced in accordance with the Java™ Realisation rules 
defined in Part 1 of this specification series. These rules aim to deliver for Java™, a developer API, provided as a 
realisation, supporting a Java™ API that represents the UML specifications. The rules support the production of both 
J2SE™ and J2EE™ versions of the API from the common UML specifications. 

The J2SE™ representation of this interface specification is provided as Java™ Code, contained in archive 
2919805V800J2SE.ZIP that accompanies the present document. 

The J2EE™ representation of this interface specification is provided as Java™ Code, contained in archive 
2919805V800J2EE.ZIP that accompanies the present document. 
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Annex D (informative): 

Description of Generic User Interaction SCF for 3GPP2 

cdma2000 networks 

This annex is intended to define the OSA API Stage 3 interface definitions and it provides the complete OSA 
specifications. It is an extension of OSA API specifications capabilities to enable operation in cdma2000 systems 
environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 architecture defined in: 

[1] 3GPP2 P.S0001-B: "Wireless IP Network Standard", Version 1.0, September 2000. 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 2.0, May 14, 2002. 

[3] 3GPP2 X.S0013: "All-IP Core Network Multimedia Domain", December 2003. 

These requirements are expressed as additions to and/or exclusions from the 3GPP specification. 

The information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3GPP 

OSA specifications. 



D.1 General Exceptions 



The terms 3GPP and UMTS are not applicable for the cdma2000 family of standards. Nevertheless these terms are used 
(3GPP TR 21.905) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no additions 
or exclusions required. 

CAMEL and CAP mappings are not applicable for cdma2000 systems. 



D.2 Specific Exceptions 
D.2.1 Clause 1: Scope 

There are no additions or exclusions. 

D.2.2 Clause 2: References 

Normative references on 3GPP TS 23.078 and on 3GPP TS 29.078 are not applicable for cdma2000 systems. 

D.2.3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

D.2.4 Clause 4: Generic and Call User Interaction SCF 

There are no additions or exclusions. 



D.2. 5 Clause 5: Class Diagrams 



The sequence diagrams are included as implementation examples. Individual specifications for the sequences for Alarm 
Call, Call Barring 1, Network Controlled Notifications, Prepaid and Pre-Paid with Advice of Charge (AoC) have yet to 
be specified. In particular, there are specifications for Call Barring, Prepaid and Pre-Paid with AoC that are 
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implemented in cdma2000 networks differently than shown in these sequence diagrams. These are for further study and 
are not part of this release. There are no additions or exclusions to this section except the Caveat stated above. 

D.2.6 Clause 6: Class Diagrams 

There are no additions or exclusions. 

D.2.7 Clause 7: The Service Interface Specifications 

There are no additions or exclusions. 

D.2.8 Clause 8: Generic User Interaction Interface Classes 
Definitions 

There are no additions or exclusions. 

D.2.9 Clause 9: State Transition Diagrams 

There are no additions or exclusions. 

D.2.10 Clause 10: Service Properties 

There are no additions or exclusions. 

D.2.1 1 Clause 1 1 : Data Definitions 

There are no additions or exclusions. 

D.2.1 2 Clause 12: Exception Classes 

There are no additions or exclusions. 

D.2.1 3 Annex A (normative): OMG IDL Description of Generic User 
Interaction SCF 

There are no additions or exclusions. 

D.2.1 4 Annex B (informative): W3C WSDL Description of Generic 
User Interaction SCF 

There are no additions or exclusions. 

D.2.1 5 Annex C (informative): Java™ API Description of Generic 
User Interaction SCF 

There are no additions or exclusions. 
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Annex E (informative): 
Change history 
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Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Old 


New 


Mar 2001 


CN 11 


NP-010134 


047 


- 


CR 29.1 98: for moving TS 29.1 98 from R99 to Rel 4 (N5-01 01 58) 


3.2.0 


4.0.0 


Jun2001 


CN_12 


NP-010330 


001 


- 


Corrections to OSA API Rel4 


4.0.0 


4.1.0 


Sep 2001 


CN 13 


NP-010468 


002 


- 


Changing references to JAIN 


4.1.0 


4.2.0 


Dec 2001 


CN 14 


NP-010598 


003 


- 


Replace Out Parameters with Return Types 


4.2.0 


4.3.0 


Dec 2001 


CN 14 


NP-010598 


004 


- 


Correction of description of sendlnfoRes() 


4.2.0 


4.3.0 


Dec 2001 


CN 14 


NP-010598 


005 


- 


Correction to handling of deassign on related object 


4.2.0 


4.3.0 


Dec 2001 


CN 14 


NP-010598 


006 


- 


Correction to Exceptions Raised in Ul 


4.2.0 


4.3.0 


Dec 2001 


CN_14 


NP-010598 


007 


- 


Correction to values of TpUllnfoType 


4.2.0 


4.3.0 


Mar 2002 


CN_15 


NP-020107 


008 


- 


Add P_INVALID_INTERFACE_TYPE exception to 
lpService.setCallback() and lpService.setCallbackWithSessionlD() 


4.3.0 


4.4.0 


Jun 2002 


CN 16 


NP-020181 


009 


- 


Addition of support for Java API technology realisation 


4.4.0 


5.0.0 


Jun 2002 


CN 16 


NP-020189 


010 


- 


Improve the vague description of P ID NOT FOUND 


4.4.0 


5.0.0 


Jun 2002 


CN_16 


NP-020182 


011 


- 


Addition of support for WSDL realisation 


4.4.0 


5.0.0 


Jun 2002 


CN 16 


NP-020189 


012 


- 


Detach call leg before playing announcement or collecting digits 


4.4.0 


5.0.0 


Jun 2002 


CN 16 


NP-020189 


013 


- 


Delete P_INVALID_CRITERIA from sendlnfoAndCollectReq() 


4.4.0 


5.0.0 


Jun 2002 


CN 16 


NP-020183 


014 


- 


Addition of Support for Network Controlled Notifications Ul 


4.4.0 


5.0.0 


Jun 2002 


CN 16 


NP-020189 


015 


- 


Correcting erroneous description of Ul behaviour in call control 


4.4.0 


5.0.0 


Sep 2002 


CN 17 


NP-020432 


018 


- 


Add text to clarify requirements on support of methods 


5.0.0 


5.1.0 


Sep 2002 


CN 17 


NP-020432 


019 


- 


Correction on use of NULL in User Interaction API 


5.0.0 


5.1.0 


Sep 2002 


CN_17 


NP-020432 


020 


— 


Correction to TpUllnfo data type to support binary data for SMS 
services 


5.0.0 


5.1.0 


Sep 2002 


CN_17 


NP-020395 


021 




Add text to clarify relationship between 3GPP and ETSI/Parlay OSA 
specifications 


5.0.0 


5.1.0 


Mar 2003 


CN 19 


NP-030021 


023 


- 


Correction to User Interaction Prepaid Sequence Diagrams 


5.1.0 


5.2.0 


Mar 2003 


CN_19 


NP-030021 


025 


— 


Correction to getNotification to remove P_INVALID_CRITERIA 
exception 


5.1.0 


5.2.0 


Mar 2003 


CN_19 


NP-030021 


028 


- 


Addition of status of methods to User Interaction interfaces 


5.1.0 


5.2.0 


Mar 2003 


CN 19 


NP-030021 


031 


- 


Corrections to User Interaction 


5.1.0 


5.2.0 


Mar 2003 


CN_19 


NP-030021 


033 


— 


Correction of User Interaction Event Notification to support non text 
encodings 


5.1.0 


5.2.0 


Mar 2003 


CN 19 


NP-030033 


029 


- 


Inconsistent description of use of secondary callback 


5.1.0 


5.2.0 


Jun 2003 


CN_20 


NP-030238 


035 


- 


Correction of the description for callEventNotify & reportNotification 


5.2.0 


5.3.0 


Jun 2003 


CN 20 


NP-030244 


036 


- 


Clarify IpUl sendlnfoReqQ 


5.2.0 


5.3.0 


Jun 2003 


CN 20 


NP-030244 


037 


- 


Update TpUllnfo for consistency with GMS capabilities 


5.2.0 


5.3.0 


Jun 2003 


CN 20 


NP-030299 


038 


1 


Specifying the origin of a GUI message 


5.2.0 


5.3.0 


Sep 2003 


CN 21 


NP-030352 


039 


- 


Correction to Java Realisation Annex 


5.3.0 


5.4.0 


Dec 2003 


CN 22 


NP-030545 


041 


- 


Correction to Ul service responseRequested logic 


5.4.0 


5.5.0 


Dec 2003 


CN 22 


NP-030553 


042 


- 


Add OSA API support for 3GPP2 networks 


5.5.0 


6.0.0 


Dec 2003 


CN 22 


NP-030554 


043 


- 


Improve User Interaction message management functions 


5.5.0 


6.0.0 


Dec 2003 


CN_22 


NP-030555 


044 


— 


Add speech recognition/synthesis capability to the Generic User 
Interaction 


5.5.0 


6.0.0 


Feb 2004 


— 


— 


— 


— 


Added Java code attachment 2919805J2EE.zip which was delivered 
late by outside developers. See Annex C. 


6.0.0 


6.0.1 


Jun 2004 


CN 24 


NP-040269 


046 


- 


Correct List vs Set semantics in User Interaction 


6.0.1 


6.1.0 


Jun 2004 


CN 24 


NP-040256 


049 


- 


Correct the P TRIGGERING ADDRESSES service property 


6.0.1 


6.1.0 


Jun 2004 


CN 24 


NP-040273 


050 


- 


Remove the <> stereotype from methods which are no longer new 


6.0.1 


6.1.0 


Sep 2004 


CN 25 


NP-040355 


052 


- 


Correct J2EE source 


6.1.0 


6.2.0 


Sep 2004 


CN 25 


NP-040356 


053 


- 


Remove unused Deprecated items 


6.1.0 


6.2.0 


Sep 2004 


CN 25 


NP-040357 


054 


- 


Add getMessageListReq() within the IpUIAdminManager interface 


6.1.0 


6.2.0 


Sep 2004 


CN 25 


NP-040357 


055 


- 


Change description of InfoAddress within TpUllnfo 


6.1.0 


6.2.0 


Sep 2004 


CN 25 


NP-040357 


056 


- 


Changes to the TpUIRecognitionGrammer parameter 


6.1.0 


6.2.0 


Sep 2004 


CN 25 


NP-040358 


057 


- 


Additional GUI Feature to support HA 


6.1.0 


6.2.0 


Sep 2004 


CN 25 


NP-040358 


058 


- 


Support High Availability at API Level 


6.1.0 


6.2.0 


Dec 2004 


CN 26 


NP-040485 


063 


- 


Removal of OSA API SCFs description in W3C WSDL 


6.2.0 


6.3.0 


Dec 2004 


-- 


- 


- 


- 


Added missing code attachments 


6.3.0 


6.3.1 


Jun 2005 


CT 28 


CP-050155 


0065 


- 


Support for Emergency Telecommunications Service 


6.3.1 


6.4.0 


Jun 2005 


CT 28 


CP-050157 


0066 


- 


Correct UlAdmin interface for sessionID problem 


6.3.1 


6.4.0 


Jul 2005 


-- 


- 


- 


- 


Added the missing Java code attachments 


6.4.0 


6.4.1 


Dec 2005 


CT_30 j 


CP-050581 


0067 


- 


Support confirmed response to reportEventNotification 


6.4.1 


7.0.0 


Jul 2006 


CT 32 


CP-060194 


0070 


- 


Resubmission of OSA API SCFs description in W3C WSDL 


7.0.0 


7.1.0 


Sep 2006 


-- 


- 


- 


- 


Added missing code attachments J2EE and J2SE. 


7.1.0 


7.1.1 


Dec 2008 


CT 42 








Upgraded unchanged from Rel-7 


7.1.1 


8.0.0 
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